설치·연결
$ minago serveminago serve 로 127.0.0.1 에 띄워요. /openapi.json·/docs(Swagger)로 명세를 확인해요.
할 수 있는 일 (6가지)
GET /v1/whoamiGET /v1/agentsGET /v1/agents/{id}DELETE /v1/agents/{id}POST /v1/agents
{ "name": "정원의 봄", "provider": "google", "sources": ["https://…", "./post.md"] }POST /v1/ghostwrite
{ "agentId": "ag_7f3a", "title": "봄맞이 베란다 정원", "autoSerp": true }▸ 요청·응답 예시
loopback(127.0.0.1) 전용이고, /v1/* 호출엔 실행별 run-token 이 필요해요(Authorization: Bearer). machineId 는 절대 노출되지 않아요.
# 포트·run-token 은 `minago serve` 실행 시 출력돼요 (기본 포트 51789)
curl http://127.0.0.1:51789/v1/whoami \
-H "Authorization: Bearer <run-token>"내 상태·사용량
GET /v1/whoami지금 내 상태랑 이번 달 사용량을 한눈에 보여드려요. 조회는 공짜예요.
{
"status": "active",
"plan": "standard",
"subscriptionStatus": "active",
"subAllowanceMicro": 10250000,
"isFirstRun": false
}작가 목록
GET /v1/agents지금까지 만든 작가들을 쭉 보여드려요.
[
{
"id": "ag_7f3a",
"name": "정원의 봄",
"status": "ready",
"createdAt": 1718200000,
"score": 18,
"verdict": "pass",
"domain": "blog.naver.com"
}
]작가 상세
GET /v1/agents/{id}작가 한 명을 골라 자세히 들여다봐요 — 말투 요약·점수까지요.
{ "agentId": "ag_7f3a" }{
"id": "ag_7f3a",
"name": "정원의 봄",
"status": "ready",
"createdAt": 1718200000,
"score": 18,
"verdict": "pass",
"domain": "blog.naver.com",
"voiceBrief": "따뜻하고 상세한 설명체",
"sources": ["blog.naver.com (3편)"]
}작가 삭제
DELETE /v1/agents/{id}이제 안 쓰는 작가는 제가 깔끔히 지워드릴게요.
{ "agentId": "ag_7f3a" }204 No Content잘 지워지면 본문 없이 끝나요(204).
작가 만들기
POST /v1/agents내 글 몇 편을 학습해 나만의 작가를 만들어요. 글이 완성될 때만 잉크가 들어요.
{
"name": "정원의 봄",
"provider": "google",
"sources": [
{ "kind": "naver-json", "text": "…", "host": "blog.naver.com" },
{ "kind": "markdown", "text": "# 어제 글\n…" }
]
}event: stage
data: { "name": "analyze", "phase": "start" }
event: tokens
data: { "in": 1200, "out": 450, "remainingMicro": 4825000 }
event: stage
data: { "name": "finalize", "phase": "end" }
event: result
data: { "verdict": "pass", "score": 18 }완성될 때까지 진행 상황을 한 줄씩 흘려보내요(SSE). 마지막 result 에 결과가 담겨요.
대필(글쓰기)
POST /v1/ghostwrite그 작가의 말투 그대로 새 글 한 편을 대신 써드려요.
{
"agentId": "ag_7f3a",
"title": "봄맞이 베란다 정원",
"category": "리빙",
"autoSerp": true,
"provider": "google",
"sources": []
}event: stage
data: { "name": "write", "phase": "start" }
event: tokens
data: { "in": 1500, "out": 2200, "remainingMicro": 2500000 }
event: result
data: { "verdict": "pass", "score": 19, "markdown": "# 봄맞이 베란다 정원\n…" }완성될 때까지 진행 상황을 한 줄씩 흘려보내요(SSE). 마지막 result 에 결과가 담겨요.
이 방식만의 참고
• loopback 전용(127.0.0.1)·기동별 토큰으로 안전해요. • 생성·대필은 기본 SSE 스트림으로 진행 상황을 보내요(대필은 마지막에 마크다운). • SSE 파서가 싫으면 Accept: application/json 또는 ?wait=1 을 주면 최종 결과 1건을 JSON+실 HTTP 상태(성공 200·부족 402·품질 422·한도 429)로 받아요. • 완성한 글은 GET /v1/library(목록)·GET /v1/library/{id}(본문)로 회수해요. • 쓰기 비용은 OpenAPI 명세에 표시돼요.