Open API 문서

TjAgentForge를 자체 시스템과 AI 클라이언트에 연결하세요. Open REST API (읽기 + 제어된 쓰기)와 MCP 서버를 제공하며, 둘 다 동일한 키, 동일한 실행 경로, 동일한 감사 기록을 공유합니다.

1. 인증

콘솔의 “API 키” 페이지에서 키를 생성하고 Authorization 헤더로 전송하세요. 지문만 저장되며 (되돌릴 수 없음), 평문은 생성 시 한 번만 표시되고 폐기는 즉시 적용됩니다.

Authorization: Bearer tjaf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

스코프: read (읽기 전용) / write (제어된 쓰기) / admin (이 테넌트의 키 관리). allow_high_risk는 별도의 스위치이며 스코프가 아닙니다.

2. REST 호출

읽기 엔드포인트 (read 스코프 필요):

curl -s https://tjagentforge.com/api/open/v1/projects \
  -H "Authorization: Bearer $TJAF_KEY"

쓰기 엔드포인트 (write 스코프 필요):

curl -s -X POST "https://tjagentforge.com/api/open/v1/tunings/$TUNING_ID/apply" \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

모든 응답은 {code, message, data} 엔벨로프를 사용합니다. code=0은 성공을 의미합니다.

3. 제어된 쓰기: Open API는 자동화 레벨을 높이지 않습니다

기본 레벨에서는 쓰기가 즉시 실행되지 않습니다. API는 confirm_url과 함께 needs_confirmation을 반환하며, 키 소유자가 콘솔에서 승인한 후에만 실행됩니다. 테넌트가 full_auto일 때만 직접 실행됩니다. 되돌릴 수 없는 고위험 작업은 항상 거부됩니다.

{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "needs_confirmation",
    "action_id": "…",
    "confirm_url": "https://tjagentforge.com/dashboard/chat?s=…",
    "expires_at": "2026-01-01T00:15:00Z"
  }
}

4. MCP 연동

MCP는 JSON-RPC 2.0을 사용하는 단일 Streamable HTTP 엔드포인트로, MCP를 지원하는 모든 클라이언트에서 사용할 수 있습니다 (REST와 동일한 API 키 인증).

핸드셰이크 및 도구 목록:

curl -s https://tjagentforge.com/api/open/mcp \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

# 列出可用工具（按密钥作用域过滤）
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

도구 호출 (쓰기 도구도 needs_confirmation을 반환합니다):

curl -s https://tjagentforge.com/api/open/mcp \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"project.list","arguments":{}}}'

5. 오류 코드

40103 — 키가 유효하지 않거나 폐기되었습니다
40302 — 스코프가 부족합니다
40303 — allow_high_risk가 필요하거나, 작업이 되돌릴 수 없어 거부되었습니다
42901 — 속도 제한 또는 작업 할당량 소진 (message 참조)

6. 기계 판독 가능한 계약

OpenAPI 설명은 Postman이나 클라이언트 생성기에 가져올 수 있습니다 (유효한 키 필요):

curl -s https://tjagentforge.com/api/open/v1/openapi.json \
  -H "Authorization: Bearer $TJAF_KEY"