API 빠른 시작

이 빠른 시작은 백엔드가 인증하고 계정을 읽을 수 있는지 확인합니다. 활성 유료 요금제, curl을 사용할 수 있는 터미널, 대시보드 → 설정 → 개발자 접근 권한이 필요합니다.

1. 최소 권한 키 만들기#

Local API quickstart라는 키를 만들고 account:read와 sites:read를 선택한 뒤 짧은 만료 기간을 고릅니다. 평문 키는 다시 표시되지 않으므로 즉시 복사하세요.

OpenAI, Anthropic, Gemini, Deepgram 또는 ElevenLabs 제공업체 키를 사용하지 마세요. 공개 API에는 maf_live_로 시작하는 Make Agent Fast 키가 필요합니다.

2. 현재 터미널에 저장#

export MAF_API_KEY="maf_live_..."

시크릿을 출력하지 않고 변수가 있는지 확인합니다.

test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"

키를 .env, 셸 기록 예제, 테스트 픽스처 또는 브라우저 번들에 커밋하지 마세요. 배포 코드에서는 호스트의 시크릿 관리자를 사용합니다.

3. 계정 확인#

curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

예상 상태는 200 OK입니다. 본문에는 data.id, 요금제와 권한 정보, 지갑 요약이 포함됩니다. 응답의 x-request-id는 실패 요청을 보고할 때 함께 보관하세요.

{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "owner@example.com",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}

/v1 경로를 바꾸지 않고 필드가 추가될 수 있습니다. 알 수 없는 필드를 이유로 응답을 거부하지 말고 무시하세요.

4. 사이트 목록#

curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

컬렉션 응답은 다음 형식을 사용합니다.

{
  "data": [],
  "has_more": false,
  "next_cursor": null
}

has_more가 true이면 정확한 next_cursor 값을 다음 요청의 cursor 쿼리 매개변수로 보냅니다. 커서를 디코딩하거나 만들지 마세요.

5. 구조화된 오류 처리#

Authorization 헤더를 잠시 제거하고 /me를 다시 호출합니다. 안정적인 코드와 함께 401을 반환해야 합니다.

{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}

프로덕션 코드는 message 비교가 아니라 error.code로 분기해야 합니다. 키는 기록하지 말고 작업, HTTP 상태, 요청 ID를 기록하세요.

6. 첫 변경을 안전하게 수행#

sites:write, agents:write, knowledge:write도 포함한 별도 키를 만들고 빠른 시작 읽기 키의 권한을 넓히지 마세요. API 레시피를 따라 명시적 멱등성 키로 사이트를 만들고 근거 지식을 추가하고 게시합니다.

첫 요청의 일반적인 오류#

범위 및 오류, API 레퍼런스, 요청 한도로 계속하세요.