REST API Reference - VEXLIT Docs

REST API v1

API 레퍼런스

단 하나의 API 호출로 CI/CD에서 보안 스캔을 자동화하세요.

지금 바로 시도하세요 — 복사, 붙여넣기, 스캔:

curl -X POST https://vexlit.ai/api/v1/scan \
  -H "Authorization: Bearer vex_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "your_project_id"}'

{
  "scan_id": "abc123-...",
  "status": "queued"
}

Read API — 모든 플랜

프로젝트, 스캔, 취약점 조회, SARIF 다운로드

scan:create — Team 플랜 + 팀 프로젝트

CI/CD 자동화를 위한 API 스캔 실행

설정

기본 URL

https://vexlit.ai/api/v1

인증

Authorization 헤더에 API 키를 포함하세요. 키는 대시보드 > API Keys에서 생성합니다.

curl -H "Authorization: Bearer vex_sk_xxxxx.yyyyy" https://vexlit.ai/api/v1/projects

플랜별 접근 권한

플랜	접근	키 수	요청 제한
Free	읽기 전용	1	30 req/h
Pro	읽기 전용	2	60 req/h
Team	전체 (읽기 + 쓰기)	3	100 req/h
Enterprise	전체 (읽기 + 쓰기)	무제한	1,000 req/h

scan:create (쓰기)는 Team 플랜 이상에서만 사용 가능하며, 팀 프로젝트에서만 작동합니다.

스코프 (권한)

Scope	설명	필요 플랜
scan:read	스캔 목록, 스캔 상세 및 SARIF 조회	모든 플랜
project:read	프로젝트 목록 조회	모든 플랜
vuln:read	프로젝트 취약점 조회	모든 플랜
scan:create	스캔 생성 및 큐 등록 (팀 프로젝트만)	Team+

에러 응답

모든 에러는 에러 코드와 사람이 읽을 수 있는 메시지의 일관된 형식을 따릅니다.

{
  "error": "plan_required",
  "message": "scan:create requires Team plan or higher. Effective plan: free"
}

HTTP	error	상황
401	unauthorized	Authorization 헤더 누락 또는 없음
401	invalid_key	API 키를 찾을 수 없거나 시크릿이 잘못됨
401	key_expired	API 키 만료
403	insufficient_scope	키에 필요한 스코프가 없음
403	plan_required	유효 플랜이 해당 작업을 지원하지 않음
403	insufficient_role	팀 멤버/뷰어는 스캔을 생성할 수 없음
403	team_project_required	개인 프로젝트에서 scan:create 시도
404	not_found	리소스를 찾을 수 없음
409	scan_in_progress	해당 프로젝트에 이미 실행 중인 스캔이 있음
429	rate_limit_exceeded	요청 제한 초과 (Retry-After 헤더 확인)

엔드포인트

GET/api/v1/projects

소유한 모든 프로젝트를 조회합니다. 프로젝트 이름, GitHub URL, 팀, 타임스탬프를 반환합니다.

Scope: project:read

curl -H "Authorization: Bearer vex_sk_xxx.yyy" \
  "https://vexlit.ai/api/v1/projects?limit=20&offset=0"

{
  "projects": [
    {
      "id": "f454d2c1-...",
      "name": "my-app",
      "github_url": "https://github.com/user/my-app",
      "team_id": "945927b0-...",
      "created_at": "2026-03-12T20:37:43Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

POST/api/v1/scan

팀 프로젝트에 새 스캔을 생성하고 큐에 등록합니다. 스캔 ID와 함께 즉시 응답합니다.

Scope: scan:create | Plan: Team+ | 팀 프로젝트만 가능

curl -X POST -H "Authorization: Bearer vex_sk_xxx.yyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-run-12345" \
  -d '{"project_id": "f454d2c1-..."}' \
  https://vexlit.ai/api/v1/scan

{
  "scan_id": "05243393-...",
  "status": "queued"
}

스캔은 비동기로 실행됩니다. GET /scans/:id로 상태를 확인하세요.

재시도 시 중복 스캔을 방지하려면 Idempotency-Key 헤더를 사용하세요.

프로젝트에 이미 대기 중이거나 실행 중인 스캔이 있으면 409를 반환합니다.

GET/api/v1/scans

스캔 목록을 조회합니다. project_id로 필터링하고 limit/offset으로 페이지네이션합니다.

Scope: scan:read

curl -H "Authorization: Bearer vex_sk_xxx.yyy" \
  "https://vexlit.ai/api/v1/scans?project_id=f454d2c1-...&limit=10&offset=0"

{
  "scans": [
    {
      "id": "de2ebc97-...",
      "project_id": "14f792b8-...",
      "status": "completed",
      "total_vulnerabilities": 68,
      "critical_count": 14,
      "high_count": 24,
      "medium_count": 19,
      "low_count": 11,
      "duration_ms": 20842,
      "created_at": "2026-03-17T02:30:26Z",
      "completed_at": "2026-03-17T02:30:47Z"
    }
  ],
  "total": 15,
  "limit": 10,
  "offset": 0
}

GET/api/v1/scans/:id

스캔 상세와 취약점 목록, 심각도 요약을 조회합니다. limit/offset으로 취약점을 페이지네이션합니다.

Scope: scan:read

curl -H "Authorization: Bearer vex_sk_xxx.yyy" \
  "https://vexlit.ai/api/v1/scans/de2ebc97-...?limit=100&offset=0"

{
  "scan": { "id": "de2ebc97-...", "status": "completed", ... },
  "summary": { "critical": 14, "high": 24, "medium": 19, "low": 11, "total": 68 },
  "vulnerabilities": [
    {
      "id": "b463b031-...",
      "rule_id": "VEXLIT-003",
      "rule_name": "Cross-Site Scripting (XSS)",
      "severity": "critical",
      "message": "Express response HTML concatenation",
      "file_path": "src/server.js",
      "line": 37,
      "cwe": "CWE-79",
      "owasp": "A03:2021",
      "suggestion": "Sanitize user input before inserting into the DOM.",
      "confidence": "high",
      "reachable": true,
      "status": "open"
    }
  ],
  "total": 68,
  "limit": 100,
  "offset": 0
}

GET/api/v1/scans/:id/sarif

완료된 스캔의 SARIF (Static Analysis Results Interchange Format)를 다운로드합니다.

Scope: scan:read | 완료된 스캔만 가능

curl -H "Authorization: Bearer vex_sk_xxx.yyy" \
  "https://vexlit.ai/api/v1/scans/de2ebc97-.../sarif" -o results.sarif

OASIS SARIF 2.1.0 형식을 반환합니다. GitHub Security 탭이나 SARIF 호환 도구에 업로드할 수 있습니다.

GET/api/v1/projects/:id/vulns

프로젝트의 최신 완료 스캔에서 취약점을 조회합니다. severity와 status로 필터링할 수 있습니다.

Scope: vuln:read

curl -H "Authorization: Bearer vex_sk_xxx.yyy" \
  "https://vexlit.ai/api/v1/projects/f454d2c1-.../vulns?severity=critical,high&status=open&limit=50&offset=0"

필터: severity=critical,high (쉼표 구분). 기본 status: open.

최신 완료 스캔의 데이터를 반환합니다. 스캔이 없으면 빈 배열을 반환합니다.

요청 제한 (Rate Limiting)

요청 제한 초과 시 Retry-After 헤더와 본문의 retry_after 필드(초 단위)가 포함됩니다.

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Upgrade plan for higher limits.",
  "retry_after": 3600
}

멱등성 (Idempotency)

POST /scan에서 Idempotency-Key 헤더를 포함하면 재시도 시 중복 스캔을 방지합니다. 1시간 내 같은 키가 전송되면 원래 스캔 ID가 반환됩니다.

curl -X POST -H "Authorization: Bearer vex_sk_xxx.yyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-build-id-12345" \
  -d '{"project_id": "f454d2c1-..."}' \
  https://vexlit.ai/api/v1/scan

멱등성 키는 API 키별로 범위가 지정되며 1시간 후 만료됩니다.

Auto-Fix PR 워크플로우

GitHub 연결 프로젝트에서 VEXLIT은 취약점을 자동 수정하고 풀 리퀘스트를 생성할 수 있습니다.

POST /scan스캔 완료취약점 감지Auto-Fix PR 생성

Auto-Fix PR은 스캔 완료 후 대시보드에서 실행됩니다. API는 스캔을 트리거하고, 프로젝트 설정에서 활성화되면 수정과 PR 생성이 자동으로 진행됩니다.