공개 API

SSemWorks 는 외부 시스템 연동을 위한 REST 공개 API(/api/v1)를 제공합니다.

API 키 발급

1. Studio → Settings → API 로 이동합니다.
2. 키 생성 — 키 전체 값은 생성 직후 한 번만 표시됩니다. 안전한 곳에 보관하세요(이후 목록에는 마스킹되어 표시).
3. 키에는 scopes(권한 범위)가 부여됩니다 — 예: workflow:read 만 가진 키는 워크플로우 조회는 되지만 목록 외 작업은 403 입니다.
4. rotate — 키를 재발급(기존 값 무효화)할 수 있습니다.

키는 ssemworks_api_ 접두사의 불투명 토큰입니다.

인증

모든 호출에 API 키를 X-N8N-API-KEY 헤더로 전달합니다(n8n 호환 계약).

curl -H "X-N8N-API-KEY: <API키>" \
  "https://<엔진 호스트>/api/v1/workflows"

• 키 미제공/무효 키는 401, scope 부족은 403 입니다.
• /api/v1 은 엔진(코어) HTTP 에 노출됩니다. 외부 공개 여부와 접근 호스트는 운영 정책에 따르므로 관리자에게 확인하세요. 트리거 게이트웨이(works-open)는 웹훅/폼 경로만 통과시키므로 /api/v1 은 게이트웨이로 접근할 수 없습니다.

엔드포인트

워크플로우

메서드	경로	설명
GET	/api/v1/workflows	목록 (limit, cursor 페이지네이션)
POST	/api/v1/workflows	생성
GET	/api/v1/workflows/{id}	단건 조회
PUT	/api/v1/workflows/{id}	수정
DELETE	/api/v1/workflows/{id}	삭제
POST	/api/v1/workflows/{id}/activate	활성화
POST	/api/v1/workflows/{id}/deactivate	비활성화
GET	/api/v1/workflows/{id}/tags	태그 조회
PUT	/api/v1/workflows/{id}/tags	태그 교체

실행

메서드	경로	설명
GET	/api/v1/executions	목록 (limit, cursor; includeData=true 로 실행 데이터 포함)
GET	/api/v1/executions/{id}	단건 조회
DELETE	/api/v1/executions/{id}	삭제
POST	/api/v1/executions/{id}/stop	실행 중단
POST	/api/v1/executions/{id}/retry	재실행(새 실행 생성, retryOf 기록)

응답 형식

• 목록: { "data": [ … ], "nextCursor": "…" } — nextCursor 를 다음 요청의 cursor 로 전달합니다.
• 단건: 리소스 객체. 오류: { "message": "…" }.

워크플로우를 URL 로 실행하려면

공개 API 가 아니라 웹훅 트리거를 사용하세요 — 워크플로우에 웹훅 트리거를 두고 Production URL 을 호출하는 것이 표준 방법입니다. → 웹훅과 폼