워크플로우

Show: All versions v2 only

워크플로우(workflow) API를 사용하면 블록(block)과 엣지(edge)로 구성된 결정적인 DAG(방향성 비순환 그래프) 기반 파이프라인(pipeline)을 만들 수 있는다. 빈 그래프(graph)나 내장 템플릿(template)으로 시작해 워크플로우를 프로그래밍 방식으로 생성하고, 동기 또는 비동기로 실행(run)하며, 실행과 로그를 조회하고, 워크플로우 정의를 YAML로 임포트(import)하거나 익스포트(export)할 수 있는다.

모든 워크플로우 라우트는 API 키로 인증되며, 해당 키를 소유한 조직(organization) 범위에서 동작한다.

참고: 대시보드 사용자는 /v1/organizations/\{org_id\}/workflows라는 조직(organization) 범위 라우트를 통해 워크플로우를 관리할 수도 있는다. 아래 라우트는 공개 API 키 인터페이스이다.

인증

모든 요청에 Bearer API 키가 포함되어야 한다:

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

기본 URL

모든 워크플로우 엔드포인트는 다음 경로에 호스팅된다:

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

워크플로우 모델

워크플로우(workflow)는 블록(block)과 엣지(edge)로 구성된 DAG(방향성 비순환 그래프)이다.

항목	타입	설명
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

새로운 워크플로우(workflow)를 생성한다. 빈 그래프(graph)에서 시작하거나 내장 템플릿(template)에서 시작할 수 있는다.

요청 본문

매개변수	타입	필수 여부	설명
name	string	예	워크플로우 이름.
description	string	아니오	선택적 설명.
template	string	아니오	내장 템플릿(template) ID 중 하나이다. graph와 함께 사용할 수 없는다.
graph	object	아니오	nodes와 edges로 구성된 초기 DAG이다.

내장 템플릿(template): 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

인증된 조직(organization)의 모든 워크플로우(workflow)를 조회한다.

예시 응답

[
  {
    "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}

전체 그래프(graph)를 포함한 단일 워크플로우(workflow) 정의를 조회한다.

경로 매개변수

이름	타입	설명
workflow_id	string	워크플로우 식별자.

에러 예시

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

PATCH /v1/workflows/{workflow_id}

워크플로우(workflow)의 메타데이터 또는 그래프(graph)를 업데이트한다. 그래프를 변경하면 검증(validate)이 실행된다.

요청 본문

매개변수	타입	필수 여부	설명
name	string	아니오	새로운 워크플로우 이름.
description	string	아니오	새로운 설명.
status	string	아니오	draft, published, 또는 archived.
graph	object	아니오	nodes와 edges로 구성된 대체 DAG이다.

참고: 워크플로우(workflow)를 실행(run)하려면 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}

워크플로우(workflow)와 그 정의를 삭제한다. 성공 시 204 No Content를 반환한다.

에러 예시

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

POST /v1/workflows/{workflow_id}/blocks

기존 워크플로우(workflow)에 블록(block)을 추가한다.

요청 본문

매개변수	타입	필수 여부	설명
type	string	예	블록(block) 타입이다. GET /v1/workflows/meta/block-types를 참조하세요.
title	string	아니오	표시 제목이다. 지정하지 않으면 블록 타입 라벨이 사용된다.
position	object	아니오	{"x": number, "y": number}. 기본값은 {"x": 0, "y": 0}이다.
config	object	아니오	블록(block)별 설정이다.

예시 요청

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}

워크플로우(workflow)에서 블록(block)을 제거한다. 연결된 엣지(edge)는 자동으로 제거된다.

경로 매개변수

이름	타입	설명
workflow_id	string	워크플로우 식별자.
block_id	string	블록 식별자.

성공 시 204 No Content를 반환한다.

POST /v1/workflows/{workflow_id}/edges

두 블록(block) 사이에 엣지(edge)를 추가한다.

요청 본문

매개변수	타입	필수 여부	설명
source	string	예	소스 블록 ID.
target	string	예	타겟 블록 ID.
source_handle	string	아니오	출력 포트(port)이다. 기본값은 output이다.
target_handle	string	아니오	입력 포트(port)이다. 기본값은 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}

워크플로우(workflow)에서 엣지(edge)를 제거한다. 성공 시 204 No Content를 반환한다.

POST /v1/workflows/{workflow_id}/run

워크플로우(workflow)를 실행(run)한다.

쿼리 매개변수

이름	타입	필수 여부	설명
mode	string	아니오	async(기본값) 또는 sync.

요청 본문

매개변수	타입	필수 여부	설명
inputs	object	아니오	워크플로우(workflow)에 전달되는 키-값 입력값이다.

비동기 실행(기본값)

비동기 실행(run)은 백그라운드 작업으로 큐에 들어갑다. 응답에 포함된 실행 ID로 GET /v1/workflows/\{workflow_id\}/runs/\{run_id\}를 폴(poll)하여 조회할 수 있는다.

예시 요청

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"
}

동기 실행

동기 실행(run)은 워크플로우(workflow)가 끝날 때까지 기다린 뒤 최종 실행 상태를 반환한다.

예시 요청

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": "Contracted scope exhausted. Contact us to extend it."
}

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

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

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

수신된 웹훅(webhook)으로 워크플로우(workflow) 실행(run)을 트리거한다. 요청 본문, 헤더, 쿼리 매개변수, 메서드, 경로가 워크플로우의 입력값으로 전달된다.

경로 매개변수

이름	타입	설명
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

워크플로우(workflow)의 실행(run) 목록을 조회한다.

예시 응답

[
  {
    "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}

블록(block) 수준 상태를 포함한 단일 실행(run)을 조회한다.

에러 예시

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

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

실행(run)의 실행 로그를 폴(poll) 형태로 조회한다.

쿼리 매개변수

이름	타입	필수 여부	설명
after_seq	integer	아니오	이 시퀀스 번호 이후의 로그를 반환한다. 기본값은 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

워크플로우(workflow) 그래프(graph)를 수정하지 않고 검증(validate)한다.

예시 응답

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

에러 예시

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

POST /v1/workflows/import

YAML에서 워크플로우(workflow)를 임포트(import)한다.

요청 본문

매개변수	타입	필수 여부	설명
yaml	string	예	YAML 워크플로우 정의.

YAML에는 version: 1, name, 그리고 최소한 하나의 블록(block)이 포함되어야 한다. code 블록은 임포트(import) 시 거부된다.

예시 요청

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

워크플로우(workflow) 정의를 YAML 또는 JSON으로 익스포트(export)한다.

쿼리 매개변수

이름	타입	필수 여부	설명
format	string	아니오	yaml(기본값) 또는 json.

yaml 형식의 응답은 text/yaml이다. json 형식의 응답은 JSON이다.

POST /v1/workflows/generate

자연어(natural language) 프롬프트로 워크플로우(workflow)를 생성한다. 이 기능은 프리미엄 기능이다.

요청 본문

매개변수	타입	필수 여부	설명
prompt	string	예	생성할 워크플로우에 대한 설명.
model	string	아니오	사용할 모델이다. 기본값은 gemini-2.5-flash-lite이다.

에러 예시

// 403
{
  "error": "upgrade_required",
  "message": "Agentic workflow generation is a premium feature. Contact us to add it to your scope."
}

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

GET /v1/workflows/meta/block-types

사용 가능한 모든 블록 타입(block type), 카테고리(category), 입력/출력 포트(port), 기본 설정을 조회한다.

GET /v1/workflows/meta/descriptors

노드(node) 디스크립터(descriptor)를 조회한다. 카테고리(category)나 검색어로 필터링할 수 있는다.

쿼리 매개변수

이름	타입	필수 여부	설명
category	string	아니오	블록 카테고리(category)로 필터링한다.
q	string	아니오	검색어.

GET /v1/workflows/meta/descriptors/grouped

카테고리(category)별로 그룹화된 노드 디스크립터(descriptor)를 조회한다.

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

단일 블록 타입(block type)의 디스크립터(descriptor)를 조회한다.

에러 예시

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

GET /v1/workflows/meta/templates

내장 워크플로우 템플릿(template)을 조회한다.

예시 응답

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

제한

제한	값	비고
워크플로우당 블록 수	100	하드 제한.
워크플로우당 엣지 수	200	하드 제한(블록 제한의 2배).
웹훅(webhook) 본문 크기	1 MB	HTTP 413으로 거부된다.
동기 실행(run) 제한 시간	60 s	전체 워크플로우 제한 시간.
블록(block)당 제한 시간	30 s	개별 블록 제한 시간.
실행 컨텍스트 크기	10 MB	전체 변수 및 출력값.
하위 워크플로우(subworkflow) 깊이	5	최대 중첩 하위 워크플로우 호출 수.

기본 실행 사용량 상한:

사용량 상한	값
external_calls_total	60
llm_calls	20
web_search_calls	10

실행 상태

실행(run)은 다음 상태 중 하나일 수 있는다:

상태	설명
pending	큐에 들어갔지만 시작되지 않음.
running	현재 실행 중.
completed	성공적으로 완료.
failed	에러로 인해 중단.
cancelled	완료 전 취소됨.

API 버전

버전	상태	비고
v1	현재	여기에 문서화된 모든 /v1/workflows/* 라우트가 현재 공개 인터페이스이다.

현재 v2 워크플로우 API는 없는다. 새로운 연동은 /v1/workflows/* 라우트를 사용해야 한다.

참고

• 워크플로우 빌더 가이드
• 버킷
• 레거시 컬렉션 API