Make Agent Fast 문서

API 레퍼런스

모든 공개 리소스, 메서드, 필수 범위, 페이지네이션 규칙, 변경 계약을 확인합니다.

이 페이지 한눈에

모든 공개 리소스, 메서드, 필수 범위, 페이지네이션 규칙, 변경 계약을 확인합니다.

API 요청 경로범위 키 → 버전 리소스 → 서명된 응답

v1123개 작업JSON

정식 머신 리더블 계약은 OpenAPI JSON입니다. 이 페이지는 사람이 읽을 수 있는 작업 색인이며 모든 엔드포인트가 공유하는 규칙을 설명합니다.

기본 URL 및 버전#

https://makeagent.fast/api/v1

주 버전은 경로에 포함됩니다. 주 버전 변경 없이 필드가 추가될 수 있으므로 알 수 없는 응답 필드는 무시하세요. 모든 관리 요청은 HTTPS와 Bearer API 키 또는 OAuth 액세스 토큰을 사용합니다.

공통 헤더#

Authorization: Bearer maf_live_...
Accept: application/json
Content-Type: application/json
Idempotency-Key: your-stable-operation-key

POST 및 PATCH JSON 본문에는 {}를 포함해 Content-Type이 필요합니다. Idempotency-Key는 선택 사항이지만 모든 POST, PATCH, DELETE에 강력히 권장합니다.

계정 및 사이트#

메서드	경로	범위	목적
`GET`	`/me`	`account:read`	계정, 요금제, 권한, 지갑 요약 읽기
`GET`	`/sites`	`sites:read`	소유 사이트 목록
`POST`	`/sites`	`sites:write`	사이트와 기본 에이전트 생성
`GET`	`/sites/{site_id}`	`sites:read`	소유 사이트 하나 읽기
`PATCH`	`/sites/{site_id}`	`sites:write`	안전한 사이트 필드 수정
`POST`	`/sites/{site_id}/publish`	`sites:write`	`{ "published": boolean }`으로 게시 또는 게시 취소
`GET`	`/sites/{site_id}/agent`	`agents:read`	에이전트 설정 읽기
`PATCH`	`/sites/{site_id}/agent`	`agents:write`	페르소나 모드, 목적, 표시 이름, 지침, 음성, 언어, 모델, 외관, 임베드 크롬, 배지, 임베드 상태, 오리진 수정
`GET`	`/sites/{site_id}/billing`	`account:read`	요금제, 결제 기간, 지갑, 애드온, 대시보드 결제 링크 읽기
`PATCH`	`/sites/{site_id}/workspace`	`team:write`	에이전트를 소유한 회사 이름 변경
`PATCH`	`/sites/{site_id}/retention`	`team:write`	대화 보관 기간 설정

사이트 생성에는 title과 content.headline이 필요합니다. 선택 필드는 slug, type, template, 추가 콘텐츠, persona_mode, en, ko, uz, ru 중 1~4개 언어입니다.

PATCH /agent는 model, appearance, embed_chrome, badge_hidden에 대시보드와 같은 요금제 검사를 적용합니다. badge_hidden: true에는 해당 요금제 또는 배지 애드온이 필요합니다.

설치 및 웹사이트 위젯#

메서드	경로	범위	목적
`GET`	`/sites/{site_id}/install`	`agents:read`	설치 대상, 임베드 상태, 허용 오리진, 설치 증거 읽기
`PATCH`	`/sites/{site_id}/install`	`agents:write`	위젯을 설치할 페이지 설정
`POST`	`/sites/{site_id}/install/check`	`agents:write`	대상 페이지에 임베드 스니펫이 적용되어 있는지 확인

지식 및 FAQ#

메서드	경로	범위	목적
`GET`	`/sites/{site_id}/knowledge`	`knowledge:read`	지식 소스 목록
`POST`	`/sites/{site_id}/knowledge`	`knowledge:write`	붙여넣은 텍스트 수집, 웹사이트 크롤링, YouTube·팟캐스트·피드 소스 가져오기
`PATCH`	`/sites/{site_id}/knowledge/{source_id}`	`knowledge:write`	`refresh_hours` 또는 바이어 팩 `approval_status` 설정
`POST`	`/sites/{site_id}/knowledge/{source_id}/recrawl`	`knowledge:write`	가져온 소스 다시 읽기 대기열 등록, `202` 반환
`DELETE`	`/sites/{site_id}/knowledge/{source_id}`	`knowledge:write`	향후 검색에서 소스 하나 삭제
`GET`	`/sites/{site_id}/faqs`	`knowledge:read`	구조화된 FAQ 목록
`POST`	`/sites/{site_id}/faqs`	`knowledge:write`	`{ "question", "answer", "approved" }` 생성
`POST`	`/sites/{site_id}/faqs/generate`	`knowledge:write`	에이전트 지식에서 FAQ 초안 작성
`POST`	`/sites/{site_id}/faqs/approve-all`	`knowledge:write`	모든 FAQ 초안 승인 및 게시
`PATCH`	`/sites/{site_id}/faqs/{faq_id}`	`knowledge:write`	질문, 답변, 승인 상태 수정
`DELETE`	`/sites/{site_id}/faqs/{faq_id}`	`knowledge:write`	FAQ 삭제
`GET` / `PATCH`	`/sites/{site_id}/fact-sheet`	`knowledge:read` / `knowledge:write`	추출된 비즈니스 팩트 시트를 읽거나, 추출이 잘못된 사실을 직접 수정
`POST`	`/sites/{site_id}/fact-sheet/reextract`	`knowledge:write`	웹사이트를 다시 읽고 팩트 시트 재구성
`POST`	`/sites/{site_id}/qa`	`knowledge:write`	선별한 질문·답변 쌍 게시
`POST`	`/sites/{site_id}/answers/revise`	`knowledge:write`	에이전트가 했어야 할 답변 가르치기
`GET`	`/sites/{site_id}/knowledge-connections`	`knowledge:read`	Notion, Drive, MCP 지식 연결 목록
`GET`	`/sites/{site_id}/knowledge-connections/connect-links`	`knowledge:read`	Notion 또는 Drive 연결을 시작하는 대시보드 URL 받기
`PATCH` / `DELETE`	`/sites/{site_id}/knowledge-connections/{connection_id}`	`knowledge:write`	동기화 주기, 선택 항목, 가져오기 도구 설정, 또는 연결 해제 및 삭제
`GET`	`/sites/{site_id}/knowledge-connections/{connection_id}/items`	`knowledge:read`	연결이 가져올 수 있는 페이지, 데이터베이스, 파일 목록
`POST`	`/sites/{site_id}/knowledge-connections/{connection_id}/sync`	`knowledge:write`	지식 연결 동기화 대기열 등록

POST /knowledge는 세 가지 본문을 받습니다. 5~~200,000자의 { "name", "text" }, 웹사이트를 크롤링하는 { "url", "max_pages", "refresh_hours" }(max_pages 1~~40, refresh_hours 1~8,760 또는 null), 그리고 { "kind": "youtube" | "podcast" | "feed", "url", "refresh_hours" }입니다. YouTube, 팟캐스트, 피드 소스는 Operate 또는 Scale이 필요하며 Launch에서는 409 conflict를 반환합니다. 파일 업로드는 대시보드 워크플로로 남습니다.

대화, 리드, 분석, 사용량#

메서드	경로	범위	목적
`GET`	`/sites/{site_id}/conversations`	`conversations:read`	대화 스레드 목록
`GET`	`/sites/{site_id}/conversations/{conversation_id}`	`conversations:read`	스레드와 페이지네이션된 메시지 읽기
`POST`	`/sites/{site_id}/conversations/{conversation_id}/reply`	`conversations:write`	비즈니스로서 방문자에게 답장
`POST`	`/sites/{site_id}/conversations/{conversation_id}/pause`	`conversations:write`	이 대화에서 에이전트를 일시 중지하고 직접 응대
`POST`	`/sites/{site_id}/conversations/{conversation_id}/resume`	`conversations:write`	대화를 다시 에이전트에게 넘기기
`GET`	`/sites/{site_id}/leads`	`leads:read`	수집된 리드 목록
`POST`	`/sites/{site_id}/leads`	`leads:write`	명시적 동의 및 연락 선호와 함께 표준 리드 생성
`GET`	`/sites/{site_id}/leads/{lead_id}`	`leads:read`	리드 하나 읽기
`PATCH`	`/sites/{site_id}/leads/{lead_id}`	`leads:write`	리드 수정·자격 판정 또는 연락 정책 변경
`POST`	`/sites/{site_id}/leads/{lead_id}/accept`	`leads:write`	리드를 영업 기회 파이프라인에 수락
`POST`	`/sites/{site_id}/leads/{lead_id}/followup`	`leads:write`	리드에게 후속 메시지 보내기
`POST`	`/sites/{site_id}/leads/{lead_id}/followup/draft`	`leads:write`	보내지 않고 후속 메시지 다시 작성
`GET`	`/sites/{site_id}/analytics`	`analytics:read`	분석 이벤트 목록
`GET`	`/sites/{site_id}/report`	`analytics:read`	집계된 분석 보고서 읽기
`POST`	`/sites/{site_id}/report/unanswered-faq`	`knowledge:write`	답변하지 못한 질문을 새 FAQ로 답변
`GET`	`/sites/{site_id}/usage`	`usage:read`	측정된 사용량 이벤트 목록

이 이벤트 및 활동 컬렉션은 limit와 cursor를 받습니다. 반환 레코드에는 개인정보가 포함될 수 있으므로 개인정보 보호 의무에 따라 저장하고 내보내세요.

소유자 답장을 지원합니다. reply, pause, resume은 대시보드와 같은 방식으로 웹 스레드나 Telegram, WhatsApp, Messenger, Instagram 채팅을 넘겨받습니다. 방문자로서 메시지를 보내는 것은 공개 API 작업이 아닙니다. 리드 수정은 지원되지만 방어 가능한 동의 기록이 없으면 consent_status: granted를 설정하지 마세요. 미확인 동의는 브로드캐스트에서 제외됩니다.

영업 기회 파이프라인과 CRM 결과#

메서드	경로	범위	목적
`GET` / `POST`	`/sites/{site_id}/pipeline/stages`	`pipeline:read` / `pipeline:write`	단계 목록 또는 설정
`GET` / `POST`	`/sites/{site_id}/pipeline/accounts`	`pipeline:read` / `pipeline:write`	비즈니스 계정 목록 또는 생성
`GET`	`/sites/{site_id}/pipeline/accounts/{account_id}`	`pipeline:read`	비즈니스 계정 읽기
`GET` / `POST`	`/sites/{site_id}/pipeline/opportunities`	`pipeline:read` / `pipeline:write`	영업 기회 목록 또는 생성
`GET` / `PATCH`	`/sites/{site_id}/pipeline/opportunities/{opportunity_id}`	`pipeline:read` / `pipeline:write`	활동 읽기 또는 담당자·가치·단계·다음 작업·사람 응답 수정
`POST`	`/sites/{site_id}/pipeline/outcomes`	`pipeline:write`	CRM 출처의 수주/실주 결과를 멱등하게 가져오기
`GET`	`/sites/{site_id}/pipeline/sync-records`	`pipeline:read`	동기화 상태, 시도, 오류 목록
`POST`	`/sites/{site_id}/pipeline/sync-records/{sync_record_id}/retry`	`pipeline:write`	저장된 페이로드로 실패한 결과 재시도
`GET` / `PATCH`	`/sites/{site_id}/pipeline-workflow`	`pipeline:read` / `pipeline:write`	영업 응답 정책 읽기 또는 수정
`GET` / `POST`	`/sites/{site_id}/pilots`	`pipeline:read` / `pipeline:write`	가이드 파일럿 목록 또는 시작
`GET`	`/sites/{site_id}/pilots/{pilot_id}`	`pipeline:read`	파일럿과 그 단계, 집계, 작업 목록 읽기
`POST`	`/sites/{site_id}/pilots/{pilot_id}/setup`, `/start`, `/stop`, `/review`, `/decision`, `/complete`, `/delete`	`pipeline:write`	파일럿을 설정, 측정, 검토, 결정, 종료 단계로 진행하거나 증거와 함께 삭제(작업 7개)
`POST`	`/sites/{site_id}/pilots/{pilot_id}/outcomes`, `/bookings`	`pipeline:write`	리드 결과 또는 예약 결과 기록(작업 2개)
`POST`	`/sites/{site_id}/pilots/{pilot_id}/report/approve`, `/report/revoke`	`pipeline:write`	공유 가능한 파일럿 보고서 승인 또는 취소(작업 2개)
`GET` / `POST`	`/sites/{site_id}/buyer-packs`	`pipeline:read` / `pipeline:write`	바이어 팩 목록, 또는 승인된 소스로 새 팩 생성
`PATCH`	`/sites/{site_id}/buyer-packs/{pack_id}`	`pipeline:write`	팩의 제목, 대상, 요약, 소스, 섹션 교체
`POST`	`/sites/{site_id}/buyer-packs/{pack_id}/approve`, `/revoke`	`pipeline:write`	팩 공유 링크 활성화 또는 비활성화(작업 2개)

제공된 CRM provider, 외부 ID, 멱등성 키는 감사 기록에 남습니다. 재시도는 실패한 레코드만 가져가며 진행 중인 외부 쓰기를 성공으로 잘못 표시하지 않습니다.

커넥터#

메서드	경로	범위	목적
`GET`	`/sites/{site_id}/connectors`	`connectors:read`	시크릿 없이 커넥터 상태 목록
`POST`	`/sites/{site_id}/connectors`	`connectors:write`	채널 연결: 자격 증명을 실시간 검증하고 웹훅을 프로비저닝한 뒤 설정 체크리스트 반환
`PATCH`	`/sites/{site_id}/connectors/{connector_id}`	`connectors:write`	`status` 또는 `reply_with_voice` 설정
`DELETE`	`/sites/{site_id}/connectors/{connector_id}`	`connectors:write`	커넥터 프로비저닝 해제 및 삭제
`POST`	`/sites/{site_id}/concierge`	`connectors:write`	플랫폼에 메시징 채널 연결 대행 요청
`GET`	`/sites/{site_id}/domains`	`domains:read`	제거됨 — `409`. 사용자 지정 도메인은 제공하지 않음
`POST`	`/sites/{site_id}/domains`	`domains:write`	제거됨 — `409`
`PATCH`	`/sites/{site_id}/domains/{domain_id}`	`domains:write`	제거됨 — `409`
`POST`	`/sites/{site_id}/domains/{domain_id}/verify`	`domains:write`	제거됨 — `409`
`DELETE`	`/sites/{site_id}/domains/{domain_id}`	`domains:write`	제거됨 — `409`

커넥터 생성은 채널로 구분되는 본문을 사용합니다. 자격 증명 필드는 telegram, whatsapp, messenger, instagram, discord, kakao마다 다르므로 시크릿을 보내기 전에 해당 커넥터 가이드를 확인하세요.

브로드캐스트, 알림, 수익화#

메서드	경로	범위	목적
`GET`	`/sites/{site_id}/broadcasts`	`broadcasts:read`	브로드캐스트 목록
`POST`	`/sites/{site_id}/broadcasts`	`broadcasts:write`	Kakao 브로드캐스트 초안 생성
`POST`	`/sites/{site_id}/broadcasts/{broadcast_id}/send`	`broadcasts:write`	기존 초안 대기열 등록, `202` 반환
`GET`	`/sites/{site_id}/notifications`	`notifications:read`	소유자 알림 목록
`POST`	`/sites/{site_id}/notifications/read-all`	`notifications:write`	이 에이전트의 모든 소유자 알림을 읽음으로 표시
`PATCH`	`/sites/{site_id}/notifications/{notification_id}`	`notifications:write`	`{ "read": boolean }`으로 읽음 또는 읽지 않음 표시
`GET`	`/sites/{site_id}/alerts`	`notifications:read`	소유자 알림 전달 채널 상태와 대시보드 링크 읽기
`GET`	`/sites/{site_id}/monetization/products`	`monetization:read`	사이트 상품 목록
`POST`	`/sites/{site_id}/monetization/products`	`monetization:write`	`access`, `consult`, `tip`, `digital` 상품 생성
`PATCH`	`/sites/{site_id}/monetization/products/{product_id}`	`monetization:write`	상품 필드와 활성 상태 수정
`DELETE`	`/sites/{site_id}/monetization/products/{product_id}`	`monetization:write`	상품 삭제

브로드캐스트 생성은 현재 kakao 채널만 받습니다. 도달 가능한 수신자가 없거나 브로드캐스트가 더 이상 초안이 아니면 대기열 등록은 409 conflict로 실패합니다.

액션, 티켓, 팀#

메서드	경로	범위	목적
`GET` / `PATCH`	`/sites/{site_id}/actions`	`agents:read` / `agents:write`	절차, 공개 웹훅, 예약 링크, 지원 티켓 읽기 또는 설정
`GET`	`/sites/{site_id}/tickets`	`tickets:read`	지원 티켓 목록
`GET`	`/sites/{site_id}/tickets/{ticket_id}`	`tickets:read`	티켓과 메시지 읽기
`PATCH`	`/sites/{site_id}/tickets/{ticket_id}`	`tickets:write`	상태, 우선순위, 선택적 담당자 설정
`POST`	`/sites/{site_id}/tickets/{ticket_id}/messages`	`tickets:write`	내부 메모 추가, 또는 `internal: false`로 고객에게 이메일 답장
`GET`	`/sites/{site_id}/team`	`team:read`	멤버, 초대, 허용된 감사 이벤트 읽기
`POST`	`/sites/{site_id}/team/invitations`	`team:write`	이메일을 보내지 않고 초대 링크 생성
`DELETE`	`/sites/{site_id}/team/invitations/{invitation_id}`	`team:write`	대기 중인 초대 취소
`PATCH` / `DELETE`	`/sites/{site_id}/team/members/{membership_id}`	`team:write`	소유자가 아닌 멤버의 역할 변경 또는 멤버 제거

개발자 웹훅 및 설정 도구#

메서드	경로	범위	목적
`GET`	`/webhook-endpoints`	`webhooks:read`	서명 시크릿 없이 엔드포인트 상태 목록
`POST`	`/webhook-endpoints`	`webhooks:write`	공개 HTTPS URL 등록 및 서명 시크릿 1회 공개
`DELETE`	`/webhook-endpoints/{endpoint_id}`	`webhooks:write`	엔드포인트 삭제 및 향후 전달 중지
`GET`	`/setup/tools`	Any valid credential	API, MCP, GitHub 연동용 설정 도구 확인
`POST`	`/setup/tools/{tool_name}`	Tool-specific	설정 도구 실행. 플랫폼 요청에는 해당 엔드포인트 범위가, GitHub 검사에는 `integrations:read`가, PR 준비에는 `integrations:write`가 필요

웹훅 URL은 HTTPS를 사용해야 하고 자격 증명이나 사용자 지정 포트를 포함할 수 없으며 공개 IP 주소로만 해석되어야 합니다.

페이지네이션#

페이지네이션 컬렉션은 1~100의 limit를 받으며 기본값은 50입니다. 반환된 불투명 next_cursor는 같은 컬렉션과 필터에만 사용하세요.

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

일부 작은 설정 컬렉션은 has_more: false인 같은 형식을 반환하며 커서가 필요하지 않습니다.

멱등성#

멱등성 키는 문자, 숫자, ., _, :, -로 구성된 8~200자여야 합니다. 결과는 24시간 유지되며 자격 증명 소유자별로 격리됩니다.

같은 키와 같은 메서드, 경로, 쿼리, 본문: 저장된 응답과 x-idempotent-replayed: true 반환
같은 키와 다른 입력: 409 conflict 반환
첫 요청 처리 중 같은 키: 409 conflict와 Retry-After: 2 반환

변경 요청 전에 키를 저장하고 해당 논리 작업의 재시도에만 재사용하세요.

응답 및 오류#

성공 응답은 리소스를 data에 넣습니다. 생성 작업은 일반적으로 201, 대기열에 들어간 브로드캐스트 전송은 202, 기타 성공 작업은 200을 반환합니다. 모든 응답에는 x-request-id가 있으며 API 데이터는 Cache-Control: no-store를 사용합니다.

전체 오류 코드 표는 범위 및 오류, 복사 가능한 워크플로는 API 레시피를 참고하세요.

MCP 클라이언트#

Streamable HTTP MCP 클라이언트를 https://makeagent.fast/api/mcp에 연결하세요. OAuth 검색을 지원하는 클라이언트는 브라우저에서 로그인과 접근 승인을 진행합니다. 승인 전에 클라이언트 ID, 회사, 요청 권한을 확인하세요. 첫 승인에서 도구가 사용하는 권한(sites:read, sites:write, agents:write, analytics:read, conversations:read, conversations:write, leads:read, leads:write, knowledge:write)을 요청하며, 이 중 하나가 없는 자격 증명은 다시 승인을 요청받습니다. 활성 요금제가 필요합니다.

수동 인증을 사용하는 클라이언트는 개발자 설정에서 범위가 제한된 API 키를 만들고 Authorization: Bearer ... 헤더로 전달하세요. 키를 소스 저장소나 브라우저 코드에 넣지 마세요. 개발자 설정에서 API 키와 OAuth 접근 권한을 취소할 수 있습니다.

읽기 도구: list_agents, get_agent, get_report, list_unanswered_questions, list_conversations, get_conversation, list_leads. 쓰기 도구: create_agent_from_website, create_agent_from_notes, test_agent, add_knowledge, save_answer, reply_to_customer, update_lead, set_website_widget. 에이전트 도구는 모두 list_agents가 반환한 agent_id를 받습니다. test_agent는 일반 답변처럼 크레딧을 사용하고, reply_to_customer는 고객에게 메시지를 보낸 뒤 해당 대화에서 에이전트를 일시 중지하며, set_website_widget은 웹사이트 채팅 위젯을 켜거나 끄며, 메시징 채널은 대시보드에서 관리합니다. MCP Apps가 활성화된 클라이언트(기본값은 인증된 Claude 연결)는 list_pending_approvals, list_action_runs, 그리고 고객이 확인한 변경을 승인하거나 거절하는 decide_approval도 받으며, 다른 클라이언트는 위 15개 도구만 봅니다. 설정 및 GitHub 연동 도구는 앱 내 설정 도우미 또는 /api/v1/setup/tools를 사용하세요.

지원 프로토콜은 2026-07-28, 2025-11-25, 2025-06-18입니다. JSON 응답을 사용하며 기존 SSE 전송이나 서버 세션은 제공하지 않습니다. MCP OAuth 토큰은 /api/mcp에서만 사용할 수 있고 REST 직접 요청에는 사용할 수 없습니다. 접근 토큰은 1시간 동안 유효하며 갱신 토큰은 교체되고 90일 후 만료됩니다. API 키는 설정한 만료 기간을 따릅니다.