Make Agent Fast 문서

API 레퍼런스

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

이 페이지 한눈에

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

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

v160개 작업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`	페르소나, 지침, 음성, 언어, 임베드 상태, 오리진 수정

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

지식 및 FAQ#

메서드	경로	범위	목적
`GET`	`/sites/{site_id}/knowledge`	`knowledge:read`	지식 소스 목록
`POST`	`/sites/{site_id}/knowledge`	`knowledge:write`	`{ "name", "text" }` 수집, 텍스트 5~200,000자
`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" }` 생성
`PATCH`	`/sites/{site_id}/faqs/{faq_id}`	`knowledge:write`	질문, 답변, 승인 상태 수정
`DELETE`	`/sites/{site_id}/faqs/{faq_id}`	`knowledge:write`	FAQ 삭제

공개 API는 붙여넣은 텍스트를 수집합니다. URL 크롤링, 파일 업로드, YouTube, 팟캐스트, 피드 워크플로는 대시보드를 사용하세요.

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

메서드	경로	범위	목적
`GET`	`/sites/{site_id}/conversations`	`conversations:read`	대화 스레드 목록
`GET`	`/sites/{site_id}/conversations/{conversation_id}`	`conversations:read`	스레드와 페이지네이션된 메시지 읽기
`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`	리드를 영업 기회 파이프라인에 수락
`GET`	`/sites/{site_id}/analytics`	`analytics:read`	분석 이벤트 목록
`GET`	`/sites/{site_id}/usage`	`usage:read`	측정된 사용량 이벤트 목록

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

방문자 메시지 전송과 소유자 답장은 공개 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`	저장된 페이로드로 실패한 결과 재시도

제공된 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`	커넥터 프로비저닝 해제 및 삭제
`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`	소유자 알림 목록
`PATCH`	`/sites/{site_id}/notifications/{notification_id}`	`notifications:write`	`{ "read": boolean }`으로 읽음 또는 읽지 않음 표시
`GET`	`/sites/{site_id}/monetization/products`	`monetization:read`	사이트 상품 목록
`POST`	`/sites/{site_id}/monetization/products`	`monetization:write`	접근, 상담, 팁, 디지털 상품 생성
`PATCH`	`/sites/{site_id}/monetization/products/{product_id}`	`monetization:write`	상품 필드와 활성 상태 수정
`DELETE`	`/sites/{site_id}/monetization/products/{product_id}`	`monetization:write`	상품 삭제

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

개발자 웹훅#

메서드	경로	범위	목적
`GET`	`/webhook-endpoints`	`webhooks:read`	서명 시크릿 없이 엔드포인트 상태 목록
`POST`	`/webhook-endpoints`	`webhooks:write`	공개 HTTPS URL 등록 및 서명 시크릿 1회 공개
`DELETE`	`/webhook-endpoints/{endpoint_id}`	`webhooks: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 레시피를 참고하세요.