ワークフロー

Show: All versions v2 only

Workflows APIを使用すると、ブロックとエッジから決定論的なDAGベースのパイプラインを構築できます。ワークフローをプログラムで作成し、同期または非同期で実行し、実行とログを確認し、ワークフロー定義をYAMLとしてインポートまたはエクスポートできます。

すべてのワークフルートはAPIキーで認証され、キーを所有する組織にスコープされています。

注意: ダッシュボードユーザーは、/v1/organizations/\{org_id\}/workflowsの組織スコープのルートを通じてワークフローを管理することもできます。以下のルートは公開APIキーのサーフェスです。

認証

すべてのリクエストにはBearer APIキーを含める必要があります：

curl -H "Authorization: Bearer $SCHIFT_API_KEY" \
  https://api.schift.io/v1/workflows

ベースURL

すべてのワークフローエンドポイントは以下にホストされています：

https://api.schift.io/v1/workflows

ワークフローモデル

ワークフローは、ブロックとエッジで構成された有向非巡回グラフ（DAG）です。

Field	Type	Description
id	string	ワークフロー識別子。
name	string	人間が読める名前。
description	string	オプションの説明。
status	string	draft、published、またはarchived。
graph.nodes	array	ワークフロー内のブロック。
graph.edges	array	ブロック間の接続。
created_at	string	ISO 8601タイムスタンプ。
updated_at	string	ISO 8601タイムスタンプ。

POST /v1/workflows

新しいワークフローを作成します。空のグラフから始めるか、組み込みのテンプレートから始めることができます。

リクエストボディ

Parameter	Type	Required	Description
name	string	Yes	ワークフロー名。
description	string	No	オプションの説明。
template	string	No	組み込みテンプレートIDの1つ。graphと相互排他的。
graph	object	No	nodesとedgesを持つ初期DAG。

組み込みテンプレート: basic_rag、document_qa、conversational_rag、multi_source_rag、agentic_rag、image_ocr_ingest、chat_rag、chatroom_memory_search。

リクエストの例

curl -X POST https://api.schift.io/v1/workflows \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Document QA",
    "description": "Upload, parse, chunk, embed, and store documents.",
    "template": "document_qa"
  }'

レスポンスの例

{
  "id": "wf_abc123def456",
  "name": "Document QA",
  "description": "Upload, parse, chunk, embed, and store documents.",
  "status": "draft",
  "graph": {
    "nodes": [
      {
        "id": "start_001",
        "type": "start",
        "title": "Start",
        "position": {"x": 100, "y": 100},
        "config": {}
      }
    ],
    "edges": []
  },
  "created_at": "2026-06-19T05:00:00+00:00",
  "updated_at": "2026-06-19T05:00:00+00:00"
}

エラーの例

// 400
{
  "detail": "Code blocks are disabled in hosted workflows"
}

GET /v1/workflows

認証された組織のすべてのワークフローをリストします。

レスポンスの例

[
  {
    "id": "wf_abc123def456",
    "name": "Document QA",
    "description": "Upload, parse, chunk, embed, and store documents.",
    "status": "draft",
    "block_count": 1,
    "updated_at": "2026-06-19T05:00:00+00:00"
  }
]

GET /v1/workflows/{workflow_id}

単一のワークフロー定義を取得し、その完全なグラフを含みます。

パスパラメータ

Name	Type	Description
workflow_id	string	ワークフロー識別子。

エラーの例

// 404
{
  "detail": "Workflow not found"
}

PATCH /v1/workflows/{workflow_id}

ワークフローのメタデータまたはグラフを更新します。グラフを変更すると、検証がトリガーされます。

リクエストボディ

Parameter	Type	Required	Description
name	string	No	新しいワークフロー名。
description	string	No	新しい説明。
status	string	No	draft、published、またはarchived。
graph	object	No	nodesとedgesを持つ置き換えDAG。

注意: ワークフローは実行する前にpublishedステータスである必要があります。

エラーの例

// 400 invalid_graph
{
  "error": "invalid_graph",
  "errors": ["Missing required input on block chunk_001"]
}

// 400
{
  "detail": "Code blocks are disabled in hosted workflows"
}

DELETE /v1/workflows/{workflow_id}

ワークフローとその定義を削除します。成功時には204 No Contentを返します。

エラーの例

// 404
{
  "detail": "Workflow not found"
}

POST /v1/workflows/{workflow_id}/blocks

既存のワークフローにブロックを追加します。

リクエストボディ

Parameter	Type	Required	Description
type	string	Yes	ブロックタイプ。GET /v1/workflows/meta/block-typesを参照。
title	string	No	表示タイトル。デフォルトはブロックタイプのラベルです。
position	object	No	{"x": number, "y": number}。デフォルトは{"x": 0, "y": 0}です。
config	object	No	ブロック固有の設定。

リクエストの例

curl -X POST https://api.schift.io/v1/workflows/wf_abc123def456/blocks \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "llm",
    "title": "Answer generator",
    "position": {"x": 400, "y": 200},
    "config": {
      "model": "gemini-2.5-flash-lite",
      "temperature": 0.7,
      "max_tokens": 1024
    }
  }'

レスポンスの例

{
  "id": "llm_7a8b9c0d",
  "type": "llm",
  "title": "Answer generator",
  "config": {
    "model": "gemini-2.5-flash-lite",
    "temperature": 0.7,
    "max_tokens": 1024
  },
  "position": {"x": 400, "y": 200}
}

エラーの例

// 400
{
  "detail": "Code blocks are disabled in hosted workflows"
}

DELETE /v1/workflows/{workflow_id}/blocks/{block_id}

ワークフローからブロックを削除します。接続されたエッジは自動的に削除されます。

パスパラメータ

Name	Type	Description
workflow_id	string	ワークフロー識別子。
block_id	string	ブロック識別子。

成功時には204 No Contentを返します。

POST /v1/workflows/{workflow_id}/edges

2つのブロック間にエッジを追加します。

リクエストボディ

Parameter	Type	Required	Description
source	string	Yes	ソースブロックID。
target	string	Yes	ターゲットブロックID。
source_handle	string	No	出力ポート。デフォルトはoutputです。
target_handle	string	No	入力ポート。デフォルトはinputです。

リクエストの例

curl -X POST https://api.schift.io/v1/workflows/wf_abc123def456/edges \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "retriever_001",
    "target": "llm_7a8b9c0d",
    "source_handle": "results",
    "target_handle": "vars"
  }'

レスポンスの例

{
  "id": "edge_a1b2c3d4",
  "source": "retriever_001",
  "target": "llm_7a8b9c0d",
  "source_handle": "results",
  "target_handle": "vars"
}

エラーの例

// 400
{
  "detail": "Source block not found: retriever_001"
}

DELETE /v1/workflows/{workflow_id}/edges/{edge_id}

ワークフローからエッジを削除します。成功時には204 No Contentを返します。

POST /v1/workflows/{workflow_id}/run

ワークフローを実行します。

クエリパラメータ

Name	Type	Required	Description
mode	string	No	async（デフォルト）またはsync。

リクエストボディ

Parameter	Type	Required	Description
inputs	object	No	ワークフローに渡されるキーと値の入力。

非同期実行（デフォルト）

非同期実行はバックグラウンドジョブとしてキューに入れられます。レスポンスには、GET /v1/workflows/\{workflow_id\}/runs/\{run_id\}でポーリングできる実行IDが含まれます。

リクエストの例

curl -X POST "https://api.schift.io/v1/workflows/wf_abc123def456/run?mode=async" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"query": "What is vector search?"}
  }'

レスポンスの例

{
  "id": "run_9f8e7d6c",
  "workflow_id": "wf_abc123def456",
  "status": "pending"
}

同期実行

同期実行はワークフローが終了するまで待機し、最終的な実行状態を返します。

リクエストの例

curl -X POST "https://api.schift.io/v1/workflows/wf_abc123def456/run?mode=sync" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"query": "What is vector search?"}
  }'

レスポンスの例

{
  "id": "run_9f8e7d6c",
  "workflow_id": "wf_abc123def456",
  "status": "completed",
  "inputs": {"query": "What is vector search?"},
  "outputs": {"answer": "Vector search finds similar vectors in a database."},
  "block_states": {
    "llm_7a8b9c0d": {
      "block_id": "llm_7a8b9c0d",
      "status": "completed",
      "inputs": {"vars": {"query": "What is vector search?"}},
      "outputs": {"response": "Vector search finds similar vectors in a database."},
      "error": null,
      "started_at": "2026-06-19T05:05:00+00:00",
      "finished_at": "2026-06-19T05:05:01+00:00",
      "duration_ms": 1200
    }
  },
  "error": null,
  "started_at": "2026-06-19T05:05:00+00:00",
  "finished_at": "2026-06-19T05:05:02+00:00"
}

エラーの例

// 409 workflow_not_published
{
  "error": "workflow_not_published",
  "message": "Publish workflow before running",
  "status": "draft"
}

// 403
{
  "detail": "Upgrade your plan to continue"
}

// 402
{
  "allowed": false,
  "reason": "quota_exceeded"
}

// 400
{
  "detail": "Workflow exceeds maximum of 100 blocks (has 120)"
}

POST /v1/workflows/{workflow_id}/webhook/{path}

受信したWebhookからワークフローの実行をトリガーします。リクエストボディ、ヘッダー、クエリパラメータ、メソッド、パスは、ワークフローの入力として渡されます。

パスパラメータ

Name	Type	Description
workflow_id	string	ワークフロー識別子。
path	string	残りのWebhookパス。

リクエストの例

curl -X POST https://api.schift.io/v1/workflows/wf_abc123def456/webhook/incoming \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "document.uploaded"}'

レスポンスの例

{
  "id": "run_a1b2c3d4",
  "workflow_id": "wf_abc123def456",
  "status": "pending"
}

エラーの例

// 413
{
  "detail": "Workflow webhook body exceeds 1MB cap"
}

// 400
{
  "detail": "Invalid JSON body: Expecting value"
}

GET /v1/workflows/{workflow_id}/runs

ワークフローの実行をリストします。

レスポンスの例

[
  {
    "id": "run_9f8e7d6c",
    "workflow_id": "wf_abc123def456",
    "status": "completed",
    "inputs": {"query": "What is vector search?"},
    "outputs": {"answer": "Vector search finds similar vectors in a database."},
    "started_at": "2026-06-19T05:05:00+00:00",
    "finished_at": "2026-06-19T05:05:02+00:00"
  }
]

GET /v1/workflows/{workflow_id}/runs/{run_id}

単一の実行を取得し、ブロックレベルの状態を含みます。

エラーの例

// 404
{
  "detail": "Workflow run not found"
}

GET /v1/workflows/{workflow_id}/runs/{run_id}/logs

実行ログをポーリングします。

クエリパラメータ

Name	Type	Required	Description
after_seq	integer	No	このシーケンス番号以降のログを返します。デフォルトは0です。

レスポンスの例

{
  "run_id": "run_9f8e7d6c",
  "status": "completed",
  "logs": [
    {"seq": 1, "level": "info", "message": "Run started", "timestamp": "2026-06-19T05:05:00+00:00"},
    {"seq": 2, "level": "info", "message": "Block llm_7a8b9c0d completed", "timestamp": "2026-06-19T05:05:01+00:00"}
  ]
}

POST /v1/workflows/{workflow_id}/validate

ワークフローグラフを変更せずに検証します。

レスポンスの例

{
  "valid": true,
  "errors": []
}

エラーの例

{
  "valid": false,
  "errors": ["Block llm_7a8b9c0d has unconnected required input"]
}

POST /v1/workflows/import

YAMLからワークフローをインポートします。

リクエストボディ

Parameter	Type	Required	Description
yaml	string	Yes	YAMLワークフロー定義。

YAMLにはversion: 1、name、および少なくとも1つのブロックが含まれている必要があります。codeブロックはインポート中に拒否されます。

リクエストの例

curl -X POST https://api.schift.io/v1/workflows/import \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "yaml": "version: 1\nname: Simple RAG\nblocks:\n  - id: start\n    type: start\nedges: []"
  }'

レスポンスの例

{
  "id": "wf_imported123",
  "name": "Simple RAG",
  "status": "draft",
  "graph": {
    "nodes": [{"id": "start", "type": "start", "title": "Start", "position": {"x": 0, "y": 0}, "config": {}}],
    "edges": []
  },
  "created_at": "2026-06-19T05:10:00+00:00",
  "updated_at": "2026-06-19T05:10:00+00:00"
}

エラーの例

// 400
{
  "detail": "Missing required field: 'version'"
}

// 400
{
  "detail": "Code blocks are disabled in hosted workflows"
}

GET /v1/workflows/{workflow_id}/export

ワークフロー定義をYAMLまたはJSONとしてエクスポートします。

クエリパラメータ

Name	Type	Required	Description
format	string	No	yaml（デフォルト）またはjson。

yamlの場合、レスポンスはtext/yamlです。jsonの場合、レスポンスはJSONです。

POST /v1/workflows/generate

自然言語のプロンプトからワークフローを生成します。これはプレミアム機能です。

リクエストボディ

Parameter	Type	Required	Description
prompt	string	Yes	生成するワークフローの説明。
model	string	No	使用するモデル。デフォルトはgemini-2.5-flash-liteです。

エラーの例

// 403
{
  "error": "upgrade_required",
  "message": "Agentic workflow generation is a premium feature. Upgrade your plan to use it."
}

// 502
{
  "error": "upstream_error",
  "message": "Workflow execution failed"
}

GET /v1/workflows/meta/block-types

利用可能なすべてのブロックタイプ、そのカテゴリ、入力/出力ポート、およびデフォルト設定をリストします。

GET /v1/workflows/meta/descriptors

ノードの記述子をリストし、カテゴリまたは検索クエリでフィルタリングできます。

クエリパラメータ

Name	Type	Required	Description
category	string	No	ブロックカテゴリでフィルタリング。
q	string	No	検索用語。

GET /v1/workflows/meta/descriptors/grouped

カテゴリ別にグループ化されたノードの記述子をリストします。

GET /v1/workflows/meta/descriptors/{block_type}

単一のブロックタイプの記述子を取得します。

エラーの例

// 404
{
  "detail": "No descriptor for block type 'unknown_block'"
}

GET /v1/workflows/meta/templates

組み込みのワークフローテンプレートをリストします。

レスポンスの例

[
  {"id": "basic_rag", "label": "Basic Rag"},
  {"id": "document_qa", "label": "Document Qa"},
  {"id": "conversational_rag", "label": "Conversational Rag"}
]

制限

Limit	Value	Notes
ワークフローあたりのブロック数	100	ハードリミット。
ワークフローあたりのエッジ数	200	ハードリミット（ブロックリミットの2倍）。
Webhookボディサイズ	1 MB	HTTP 413で拒否されます。
同期実行タイムアウト	60 s	ワークフローの合計タイムアウト。
ブロックごとのタイムアウト	30 s	個々のブロックタイムアウト。
実行コンテキストサイズ	10 MB	変数と出力の合計。
サブワークフローの深さ	5	最大ネストされたサブワークフロー呼び出し。

デフォルトの実行支出上限：

Cap	Value
external_calls_total	60
llm_calls	20
web_search_calls	10

実行ステータス

実行は次のいずれかの状態になります：

Status	Description
pending	キューに入れられたが開始されていない。
running	現在実行中。
completed	正常に終了。
failed	エラーのため停止。
cancelled	完了前にキャンセル。

APIバージョン

Version	Status	Notes
v1	Current	ここに文書化されているすべての/v1/workflows/*ルートは現在の公開サーフェスです。

現在、v2 Workflows APIはありません。新しい統合は/v1/workflows/*ルートを使用する必要があります。

参照

• ワークフロービルダーガイド
• バケット
• レガシーコレクションAPI