개발자 문서

API 문서

퓨쳐인프라 API는 서버 생성·앱 배포·DNS·AI 호출·결제를 REST 로 다루는 개발자용 인터페이스입니다. 웹 콘솔이 쓰는 API와 완전히 같습니다. 화면에서만 되는 기능은 없고, 같은 API 를 MCP 로 AI 에이전트가 직접 씁니다.

API 키 발급 MCP 연동

서비스별 문서

각 문서는 할 수 있는 것만이 아니라 어디서 막히는지를 함께 적었습니다.

조직·멤버 — 한 조직에 여러 사람, 한 사람이 여러 조직. 결제는 조직마다 따로
프로젝트 — 고객사별로 묶고, 청구를 나누고, 통째로 넘기기
앱 (도커) — 이미지 하나로 주소까지. 정지와 삭제의 차이
DNS 호스팅 — 가도메인·연결·호스팅 셋의 구분, 위임 전에는 아무 일도 안 일어납니다
세컨브레인 — 기록은 지우지 않고 잊습니다. 스킬은 표준 그대로
MCP 연동 — AI 에이전트가 직접 다루게 하기

인증

프로그램은 API 키, 사람은 로그인 세션을 씁니다.

Authorization: Bearer pk_live_xxxxxxxxxxxx

키는 발급할 때 한 번만 보여줍니다. 키마다 권한(스코프)과 월 한도를 따로 걸 수 있습니다.

기본 주소

https://futureinfra.ai/v1

영역	경로	하는 일
클라우드	`/v1/cloud`	서버 생성·전원·스냅샷·고정 IP·방화벽·이미지
도메인	`/v1/domain`	서브도메인·DNS·도메인 등록
AI	`/v1/ai`	LLM·이미지·영상·음성
결제	`/v1/billing`	잔액·거래내역·요금표·트래픽 사용량·쿠폰 등록
키·감사	`/v1/keys`, `/v1/audit`	키 발급·회수, 호출 기록
승인	`/v1/approvals`	되돌릴 수 없는 작업의 대기열

쿠폰은 콘솔의 크레딧 → 쿠폰 등록에서, 또는 POST /v1/billing/coupons/redeem {"code":"FI-XXXX-XXXX"}로 등록합니다. 사람 세션 전용(billing:write)이라 API 키·MCP로는 등록할 수 없고 조회(GET /v1/billing/coupons)만 됩니다. 한 조직에 한 번, 들어온 크레딧은 서비스 크레딧(promo)입니다.

서버 만들기

POST /v1/cloud/instances
{
  "name": "web",
  "blueprint": "debian-13",
  "plan": "small",
  "sshKey": "ssh-ed25519 AAAA..."
}

202 Accepted
{ "vmid": 312, "domain": "vm-312.futureinfra.ai", "status": "provisioning" }

바로 응답하고 뒤에서 만듭니다. GET /v1/cloud/instances 로 상태가 running 이 되는지 보세요.

승인이 필요한 작업

서버 삭제, 스냅샷 되돌리기, 도메인 구매처럼 되돌릴 수 없는 일입니다.

DELETE /v1/cloud/instances/312

202 Accepted
{ "pending_approval": true, "approvalId": "..." }

# 콘솔에서 승인한 뒤 같은 요청을 헤더와 함께 다시 보냅니다
DELETE /v1/cloud/instances/312
X-Approval-Id: ...

오류

코드	뜻
`insufficient_credits`	잔액이 모자랍니다. 최소 1시간치가 필요합니다.
`key_spend_cap_reached`	이 키의 월 한도를 넘었습니다.
`instance_limit_reached`	등급의 서버 개수 한도입니다.
`label_reserved`	서비스 예약어라 쓸 수 없는 서브도메인입니다.
`no_public_ip`	포트를 열려면 고정 IP를 먼저 배정해야 합니다.
`region_not_allowed`	콘솔 로그인은 국내에서만 가능합니다. (API 키는 해당 없음)