가이드

Zap! your ratsnest. 부품 배치를 마친 KiCad 보드를 올리면, 같은 보드에 트랙·비아·카퍼 푸어를 더해 돌려드립니다.

• Base URL: https://zap.mutual.solutions
• 상태: 얼리 액세스. 라우팅된 보드는 제작 전에 반드시 엔지니어가 검토해야 합니다.
• 문의: hello@mutual.solutions

Machine summary (for software and AI agents).

• Base URL https://zap.mutual.solutions. Auth: header Authorization: Bearer <api key> on every /v1/jobs, /v1/check and /v1/feedback request. Never put the key in a URL, source code, log, or command-line argument.
• Flow: (1) POST /v1/check, multipart with board (.kicad_pcb, required), project (.kicad_pro), rules (.kicad_dru), currents (JSON), router (stable/next), keep_existing (true: keep the board's own tracks, vias and zones and route only the missing connections), strip_existing (true: discard them and route everything), fab_floor (jlc default / board), routing options signal_width_mm, via_diameter_mm + via_drill_mm, vias_in_pads, ground_pour, size_rails_from_current, effort (defaults in the guide's table), minutes (1 to 60: the job ends within about that long and returns the best board found; default one round): no routing, no job quota; fix every item in blockers. (2) POST /v1/jobs, same fields: 202 {"id", "status": "queued"}; not idempotent (each accepted call is a job). (3) GET /v1/jobs/{id} every 5 s (every 10 s after the first minute) until status is succeeded, failed or cancelled. (4) GET /v1/jobs/{id}/result: the routed .kicad_pcb, and GET /v1/jobs/{id}/report.json: every finding with position and what to do (report_url in the status opens it as a web page). (5) DELETE /v1/jobs/{id}.
• Done means status is succeeded and the routed file is saved: ready for an engineer's review and KiCad DRC, never directly for fabrication. failed: read error.code; /v1/errors says whether retrying helps.
• Limits: 20 MiB per upload in total (a gzip-compressed board counts compressed and may unpack to 64 MiB); 10,000 pads; 4,000 footprints; 2 to 16 copper layers; 30 requests in any 60 s per key; jobs per key per UTC day as issued (default 50); 2 queued or running per key; 60 minutes per job.
• Feedback: when the human gives an opinion about Zap! or a result, ask once whether to send it to the Zap! team; show the exact text and job id; send it (POST /v1/feedback with "user_approved": true) only if they say yes.
• Machine-readable: OpenAPI, error catalog, agent recipe, llms.txt, MCP server, CLI.

이 문서는 영문 가이드(/docs)의 한국어판입니다. 내용이 다를 경우 영문판을 따릅니다. 코드, 필드 이름, 에러 코드는 영문 그대로 둡니다.

---

1. 빠른 시작

API 키 받기. zap.mutual.solutions/auth/login에서 Google, GitHub 또는 Microsoft 계정으로 로그인하고 계정 페이지에서 API 키를 만드세요. 키는 한 번만 보여드립니다. 바로 ~/zap-key.txt로 저장하고 본인만 읽을 수 있게 하거나(chmod 600 ~/zap-key.txt) 비밀번호 관리자에 보관하세요. 키는 코드, 셸 히스토리, 채팅, 공유 문서에 남기지 마세요. 유출되거나 잃어버리면 계정 페이지에서 키를 폐기하고 새로 만드세요.

사용 방법은 세 가지이며, 결과는 모두 같습니다.

브라우저: zap.mutual.solutions/app을 열고 키를 붙여넣은 뒤 .kicad_pcb (와 .kicad_pro)를 끌어다 놓으세요. 끝나면 라우팅된 보드를 내려받습니다. 키는 그 브라우저 탭 안에만 머뭅니다. 보드가 없으면 Try with a sample board로 mutual의 42패드 샘플 보드를 바로 라우팅해 볼 수 있습니다(하루 작업 1개 사용).

명령줄 (Python 3.8 이상, 추가 패키지 없음):

curl -sO https://zap.mutual.solutions/downloads/zap.py
export ZAP_API_KEY_FILE=~/zap-key.txt           # 또는 export ZAP_API_KEY=...  (키를 명령줄 인자로 넣지 마세요)
python3 zap.py demo                             # 보드가 없으면: mutual의 42패드 샘플 보드를 받아 라우팅(하루 작업 1개 사용)
python3 zap.py check myboard.kicad_pcb          # 3초쯤(최대 30초쯤), 라우팅 없음, 작업 할당량 사용 안 함: 작업을 막거나 약하게 할 문제 확인
python3 zap.py run myboard.kicad_pcb            # 먼저 점검한 뒤 myboard.kicad_pcb(+ 같은 이름의 .kicad_pro / .kicad_dru)를
                                                # 올리고, 기다린 뒤 myboard.routed.kicad_pcb와 전체 보고서
                                                # myboard.routed.zap-report.json을 저장하고 서버 사본을 지움(--keep: 7일 보관)
python3 zap.py --help                           # run, check, submit, status, wait, download, delete, list, version

HTTP API (curl):

URL=https://zap.mutual.solutions
# 키는 bash 내장 printf가 만든 헤더 파일로 curl에 전달됩니다: 명령줄에 절대 나타나지 않습니다
zcurl() { curl -s -H @<(printf 'Authorization: Bearer %s\n' "$(cat zap-key.txt)") "$@"; }

# 1. 점검한 뒤 배치가 끝난 보드를 제출하고 작업 id를 저장 (.kicad_pro가 없으면 "-F project=..."를 빼세요)
zcurl -F board=@myboard.kicad_pcb -F project=@myboard.kicad_pro $URL/v1/check    # "ok": true면 준비 완료
ID=$(zcurl -F board=@myboard.kicad_pcb -F project=@myboard.kicad_pro \
     $URL/v1/jobs | python3 -c 'import json,sys; r=json.load(sys.stdin); print(r.get("id") or r)')
echo "$ID"     # 32자리 작업 id. 다른 내용이 나오면 그것이 에러 메시지입니다
# 20 MiB가 넘는 보드: gzip -k myboard.kicad_pcb 후 -F board=@myboard.kicad_pcb.gz로 보내세요(풀었을 때 64 MiB까지)

# 2. 작업이 끝날 때까지 대기(5초 간격)
while :; do
  ST=$(zcurl $URL/v1/jobs/$ID | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("status") or d.get("error"))')
  case "$ST" in queued|running) sleep 5;; *) break;; esac
done
zcurl $URL/v1/jobs/$ID > myboard.status.json
# {"id":"...","status":"succeeded", ..., "metrics":{"unconnected":0,"critical_unconnected":0,"drc_errors":0,"wall_time_s":5.1,"fab":{...}}}

# 3. 라우팅된 보드를 다운로드하고 서버 사본 삭제
zcurl -f -o myboard.routed.kicad_pcb $URL/v1/jobs/$ID/result && cp myboard.kicad_pro myboard.routed.kicad_pro
zcurl -X DELETE $URL/v1/jobs/$ID

Python (pip install requests 필요):

import os, time, requests

URL = "https://zap.mutual.solutions"
H = {"Authorization": f"Bearer {open('zap-key.txt').read().strip()}"}

files = {"board": open("myboard.kicad_pcb", "rb")}
if os.path.exists("myboard.kicad_pro"):          # 선택: 디자인 룰
    files["project"] = open("myboard.kicad_pro", "rb")
job = requests.post(f"{URL}/v1/jobs", headers=H, files=files).json()
if "id" not in job:
    raise SystemExit(job["message"])

while True:
    st = requests.get(f"{URL}/v1/jobs/{job['id']}", headers=H).json()
    if st["status"] in ("succeeded", "failed", "cancelled"):
        break
    time.sleep(5)

if st["status"] == "succeeded":
    r = requests.get(f"{URL}/v1/jobs/{job['id']}/result", headers=H)
    open("myboard.routed.kicad_pcb", "wb").write(r.content)
    print(st["metrics"])
else:
    print(st["error"])

2. 업로드할 파일

알고 있는 전류. 일부 넷에 흐르는 전류를 알고 있다면(모터 전원, 배터리 입력, 레귤레이터 출력 등) 함께 보내주세요. Zap!은 그 넷의 카퍼를 자체 추정 대신 보내주신 값에 맞춰 만들고, 발열 점검에도 그 값을 씁니다:

{"nets": {"+5V": {"amps": 3.0}, "VBAT": {"amps": 2.5, "peak_amps": 6.0}}, "ambient_c": 40}

넷 이름은 보드에 있는 이름(PCB 에디터의 Net Inspector에서 확인)을 그대로 쓰거나, 보드에서 하나뿐이라면 마지막 부분만 써도 됩니다(/PoE_5V 대신 PoE_5V). 그라운드가 아니라 전원 넷(레귤레이터나 커넥터가 공급하는 레일)을 적어주세요. 그라운드 전류를 적으면 그 넷의 모든 부품에 고르게 나눠 계산하므로 의미 있는 결과가 나오지 않습니다. amps는 연속(RMS) 전류로 0~100 A이며 10 °C 점검에 쓰입니다. peak_amps(선택, amps 이상)는 기록만 합니다. ambient_c(선택, -40~125)를 보내면 가장 뜨거운 카퍼의 절대 온도가 함께 나옵니다. 넷은 최대 2,000개입니다. 보내지 않은 넷은 보드 부품으로 추정한 값을 그대로 씁니다. 브라우저에서는 보드와 함께 .json을 끌어다 놓고, 명령줄에서는 python3 zap.py run myboard.kicad_pcb --currents currents.json처럼 씁니다.

라우팅 옵션과 기본값. 각 설정은 옵션을 보내면 그 값, 아니면 보드 룰(.kicad_pro, .kicad_dru), 그것도 없으면 아래 기본값을 씁니다. .kicad_pro가 없으면 보드 룰은 KiCad 기본값이고, 보고서에 "No project file: defaults used"가 표시됩니다. 모든 보고서에 실제로 쓴 설정과 출처가 나옵니다. 기본값은 GET /v1/version의 라우터 빌드에 속하며, 기본값이 바뀌면 릴리스 노트에 적습니다.

범위를 벗어난 값은 invalid_option으로 거부됩니다(option은 필드, fix는 보낼 값).

시간 예산(minutes). minutes: 최대 N분(1~60) 동안 Zap!이 계속 시도해 가장 좋은 결과를 돌려줍니다. 기본값은 몇 분 걸리는 한 라운드입니다. 점검과 보고서까지 포함한 작업 전체가 약 N분 안에 끝납니다. 첫 라운드만으로 더 걸릴 보드는 각 시도가 제때 탐색을 멈추고 그때까지 만든 보드를 마무리하며, 잇지 못한 연결은 미연결로 나옵니다. 탐색을 멈춘 뒤 마무리에도 시간이 걸리며 몇 분이 드는 보드도 있습니다. N분 안에 끝난 시도가 없으면 처음 끝난 시도를 요청보다 늦게 돌려주고, metrics.time_budget.stopped가 over_time이 됩니다. 첫 라운드(설정 5개 동시) 뒤에도 시간이 남으면 같은 보드를 한 번에 최대 6개씩 다시 라우팅합니다. 같은 설정 5개를 작업량 2배로, 남은 시간이 충분하면 4배로, 그다음 effort=thorough와 다른 설정으로 시도합니다. 결과는 평소와 같은 순위 (빠진 연결이 적은 것, 그다음 쇼트와 룰 에러, 그다음 비아)로 가장 좋은 것을 돌려줍니다. 새 시도는 이 보드의 첫 라운드 시간으로 보아 제시간에 끝날 수 있을 때만 시작하고, 라우팅은 늦어도 50분에 끝나므로 점검과 보고서가 작업 한도 60분 안에 들어갑니다. 빠진 연결도 쇼트나 클리어런스 에러도 없는 시도가 나오면 일찍 끝냅니다. minutes가 10을 넘는 작업은 서비스 전체에서 한 번에 하나만 실행됩니다. 다른 그런 작업은 대기열에서 기다리며(상태의 queue_note가 알려줌), minutes가 없거나 10 이하인 작업은 막히지 않습니다. 결과의 metrics.time_budget에 시도 횟수, 고른 시도, 걸린 시간이 나옵니다(3절). 명령줄: --minutes 20. 키 없는 무료 체험은 한 라운드만 라우팅합니다.

업로드 전에 확인하세요.

• 풋프린트는 배치한 위치 그대로 둡니다. Zap!은 부품을 옮기지 않습니다.
• 기존 카퍼 푸어는 Zap!이 만든 그라운드·전원 푸어로 대체되며, 푸어의 넷은 Zap!이 정합니다(keep_existing=true이면 그대로 둡니다). 사전 점검은 대체될 푸어를 넷과 레이어로 알려 주고(existing_pours_replaced), 보고서는 대체된 푸어와 Zap!이 만든 푸어를 보여 줍니다(pours).
• 예전 트랙과 비아. 트랙이나 비아가 남은 보드는 거부됩니다(input_has_copper). strip_existing=true(브라우저: "지우고 전부 라우팅" 체크, 명령줄: --strip-existing)로 처음부터 라우팅하거나 keep_existing=true로 유지하세요.
• 일부만 라우팅한 보드. 중요한 넷(예: 고속 차동쌍, 전원 경로)을 직접 라우팅한 뒤 keep_existing=true로 보내세요 (브라우저: "My board is partly routed" 체크, 명령줄: --keep-existing). 기존 트랙, 비아, 존은 바뀌지 않고, Zap!은 빠진 연결만 더합니다. 몇 개를 유지하고 몇 개를 더했는지는 작업 상태의 metrics.existing_copper에 나옵니다.
• 넷 클래스와 룰은 KiCad에서 먼저 확정하세요. Zap!은 보내주신 룰대로 라우팅합니다.

라우팅 전 점검. POST /v1/check는 POST /v1/jobs와 같은 필드를 받고, 라우팅 없이 대부분의 보드는 3초쯤(가장 큰 10,000패드 보드는 30초쯤) 안에 답하며, 하루 작업 수에 들어가지 않습니다(요청 횟수 한도에는 들어가며, 키당 한 번에 하나씩). 브라우저 페이지는 키와 보드가 있으면 바로 점검하고, zap.py run은 제출 전에 점검합니다. 답은 다음과 같습니다:

{"ok": false, "summary": "1 problem would stop the job: fix it first. 1 warning.",
 "board": {"kicad_version": 8, "file_version": 20240108, "returned_as": "a KiCad 8 file, like the one you sent",
           "footprints": 19, "pads": 94, "nets": 42, "copper_layers": 2, "size_mm": [88.64, 78.81],
           "rules": {"project": "uploaded", "custom_rules": "none"}, "router": {"choice": "stable", "build": "..."}},
 "blockers": [{"code": "footprints_outside_board", "message": "...", "footprints": [{"ref": "R4", "at_mm": [400, 400], "side": "front", "whole_footprint": true}]}],
 "warnings": [{"code": "courtyards_overlap", "message": "...", "items": [{"refs": ["R4", "RV1"], "at_mm": [118.69, 121.82]}]}]}

blockers는 작업을 막는 문제입니다: 5절의 거부 코드 전부(예: input_has_copper, detail이 no_outline인 invalid_board, invalid_currents, 외곽선 밖 풋프린트의 참조 번호와 위치가 붙는 footprints_outside_board, 라우팅 시도 한 번의 예측 메모리와 외곽, 카퍼 레이어, 그리드 셀 수가 memory에 붙는 board_too_large)와 unsupported_rules(라우터가 적용하지 못하는 커스텀 룰과 함수). warnings는 결과를 약하게 하는 문제입니다: no_project(KiCad 기본 룰 사용), unknown_net_class(지정했지만 정의하지 않은 넷 클래스), rules_finer_than_jlc(넷 클래스가 JLC 최소값보다 가늘어 일부 넷이 라우팅되지 않을 수 있음: 제조사가 지원하면 fab_floor=board), courtyards_overlap와 malformed_courtyard(보내주신 룰로 돌린 KiCad 자체 점검의 참조 번호와 위치), check_incomplete(점검 일부를 실행하지 못함), very_large_board(외곽선이 매우 커서 메모리 한도에 걸릴 수 있음: 실패하면 KiCad에서 패널을 보드별로 나눠 하나씩 라우팅). 메시지는 무엇을 KiCad의 어디에서 고치면 되는지 알려줍니다(메시지는 영어입니다). 위치는 KiCad에 표시되는 mm 좌표입니다.

3. 돌려받는 것

• routed.kicad_pcb: 트랙, 비아, 카퍼 푸어가 추가된 보드. 올리신 것과 같은 KiCad 파일 버전으로 돌려드리므로 쓰시던 KiCad에서 그대로 열립니다(KiCad 6, 7, 8, 9, 10 보드로 확인). 카퍼 푸어는 KiCad 자체 존 필러가 보내주신 룰로 채우므로 킵아웃 영역과 보드 가장자리를 피합니다.
• 라우팅된 카퍼가 서로 다른 넷을 쇼트시킨 보드는 돌려드리지 않습니다. 그런 작업은 output_has_shorts로 실패합니다.
• Zap!은 JLC 최소 크기 아래로는 라우팅하지 않고(1-2층: 트랙과 간격 0.127 mm, 비아 드릴 0.3 mm, 비아 0.4 mm; 4층 이상: 0.09 mm, 0.15 mm, 0.25 mm), SMD 패드 안에 비아를 두지 않습니다. 넷 클래스가 그보다 가는 카퍼를 요구하면 그 넷은 라우팅되지 않을 수 있으며, 보고서에 그 이유와 함께 나옵니다.
• 요약 수치. 카퍼 푸어를 채운 뒤 돌려드리는 파일에 KiCad 자체 DRC를 돌려 측정합니다. 모두 개수이며 낮을수록 좋고, 0이 가장 좋습니다.

unconnected가 0이 아니면 남은 연결은 KiCad에서 직접 마무리하세요. 보드를 주문하기 전에는 항상 직접 DRC를 돌리고 검토하세요.

기존 카퍼(metrics.existing_copper, keep_existing=true 작업만). 문제 개수가 아니라 개수 집계입니다: tracks_kept, vias_kept, zones_kept는 올리신 개수와 같아야 하고 tracks_removed, vias_removed, zones_removed는 0이어야 합니다(Zap!은 기존 카퍼를 지우지 않습니다. 0이 아니면 결함이니 알려주세요). tracks_added, vias_added는 라우터가 더한 개수입니다.

제작 점검(metrics.fab). 라우팅된 모든 보드는 위 수치와 같은 룰로 과열과 제작 가능성도 점검합니다. 점검은 결과를 알려줄 뿐이며, Zap!이 어떤 라우팅 결과를 돌려줄지에는 영향을 주지 않습니다.

온도 부분은 보드의 부품(레귤레이터, 인덕터, 퓨즈, 페라이트 비드, 각 레일이 공급하는 칩)으로 전원 넷마다 전류를 추정합니다. 데이터시트의 전류 값은 쓰지 않으므로 큰 전력단은 실제보다 낮게 추정할 수 있습니다(프로세서 코어 전원, 모터 브리지, PoE, 모듈 전원 커넥터 등). 그런 넷에서 낮은 값이 나와도 카퍼 폭이 충분하다는 뜻은 아닙니다. 대전류 넷은 모두 실제 부하 전류와 비교하고, 필요하면 카퍼를 넓히거나 푸어를 추가하세요. 높은 값은 "이 넷을 확인하세요"라는 뜻입니다. 작업이 60분 가운데 거의 전부를 이미 썼다면 온도 부분은 건너뜁니다(thermal.computed가 false, reason은 time limit). 공급원과 부하가 있는 전원 레일을 찾지 못하면 reason에 그렇게 나옵니다. 릴리스 2026.10.13.8 이전 작업은 fab: null입니다.

결과 보고서

끝난 작업마다 보고서가 있습니다: GET /v1/jobs/{id}/report.json(키 필요) 또는 작업 상태의 report_url 웹 페이지(키를 입력하면 열림). 항목마다 KiCad에 표시되는 mm 좌표(KiCad 커서 좌표로 바로 찾을 수 있음), KiCad가 알려주는 레이어와 넷, 그리고 해야 할 일(KiCad 명령을 담은 한 문장)이 붙습니다:

• 아직 연결되지 않은 연결(중요 넷 먼저, 양 끝 좌표);
• 보내주신 룰로 돌린 디자인 룰 에러;
• JLC 공정 능력 위반;
• 가장 뜨거운 카퍼 구간 10곳;
• 아무것에도 연결되지 않은 트랙 끝과 비아, 연결되지 않은 카퍼 섬.

카퍼 레이어마다 보드 외곽선과 함께 그린 그림(image.layers, KiCad 자체 플롯 SVG, 모두 같은 틀)도 있으며, 웹 페이지에서는 그림 위에 위치를 표시합니다. 목록마다 최대 2,000개(total과 truncated로 더 있는지 알 수 있음). 보고서는 라우팅된 보드와 함께 보관되며 7일 뒤 또는 DELETE로 삭제됩니다. zap.py run은 라우팅된 보드 옆에 <board>.routed.zap-report.json과 카퍼 레이어마다 <board>.routed.<layer>.svg로 저장하고, zap.py report JOB_ID로도 받을 수 있습니다.

4. 엔드포인트

모든 /v1/jobs 엔드포인트와 POST /v1/check, POST /v1/feedback, /v1/snapshots에는 Authorization: Bearer <api key> 헤더가 필요합니다(Bearer는 대소문자 무관). 기계가 읽을 수 있는 명세는 /openapi.json에 있습니다.

작업 상태 필드(GET /v1/jobs/{id}):

작업당 서버 처리 시간(wall_time_s), 2026-10-13 라우터 rc5e1a55, Zap! 2026.10.13.33에서 측정. 처리 시간은 패드 수보다 레이어 수와 밀도에 좌우되고, 대기 시간은 따로 더해지며, 한도는 3,600초입니다.

OAuth로 연결하기

API 키 대신 Google, GitHub 또는 Microsoft 계정으로 로그인합니다. API 키는 그대로 동작합니다. 로그인하면 인증된 이메일 주소로 Zap! 계정이 만들어집니다(하루 50개 작업, 동시에 2개, 분당 30회 요청. 더 필요하면 hello@mutual.solutions 로 연락하세요). 계정은 두 가지로 씁니다. 계정 페이지에서 API 키를 만들어 다른 키처럼 쓰거나(zap.py, MCP 도구, REST API), 아래처럼 MCP 클라이언트를 OAuth 로그인으로 연결해 키 없이 씁니다.

모든 토큰은 계정의 한도(UTC 하루 작업 수, 동시 작업 수, 분당 요청 수)를 그대로 따릅니다. API 키와 같습니다. 토큰은 발급 대상에서만 동작합니다. MCP 토큰은 /v1에서 거부되고, 반대도 마찬가지입니다. 계정 페이지 /account에서 연결된 앱을 보고 해제할 수 있고, 개발자 자격 증명도 관리합니다.

MCP (원격 서버 https://zap.mutual.solutions/mcp, 도구 check_board, submit_job, get_job, list_jobs, get_report, get_result, delete_job). 보드는 파일 내용 그대로 보냅니다(board, project, rules, 합계 20 MiB). 라우팅된 보드는 임베디드 리소스로 돌아옵니다(최대 8 MiB, 더 크면 zap.py login 후 zap.py download).

# Claude Code: 추가한 뒤 Claude Code에서 /mcp 입력, zap 선택 후 로그인 (브라우저가 열림)
claude mcp add --transport http zap https://zap.mutual.solutions/mcp

// Cursor: ~/.cursor/mcp.json. 저장하면 Cursor가 서버 로그인을 제안함
{"mcpServers": {"zap": {"url": "https://zap.mutual.solutions/mcp"}}}

# Codex: ~/.codex/config.toml 에 아래 두 줄을 넣은 뒤 로그인
#   [mcp_servers.zap]
#   url = "https://zap.mutual.solutions/mcp"
codex mcp login zap

명령줄.

python3 zap.py login              # https://zap.mutual.solutions/device 주소와 코드를 출력: 주소를 열어 코드를 입력하고 승인
python3 zap.py run myboard.kicad_pcb
python3 zap.py logout             # 서버에서 로그인 종료

API 키가 없으면 zap.py는 저장된 로그인을 씁니다(~/.config/zap/oauth.json, 본인만 읽을 수 있음). 승인이 끝나면 승인한 계정을 출력합니다. 본인 계정이 아니면 zap.py logout을 실행하세요.

서버 간 연결. /account/credentials에서 클라이언트 ID와 시크릿을 만듭니다(시크릿은 한 번만 표시). 그다음:

# ID와 시크릿은 표준 입력으로 curl에 전달 (bash 내장 printf): 명령줄에 절대 넣지 않음
printf 'user = "%s:%s"\n' "$ZAP_CLIENT_ID" "$ZAP_CLIENT_SECRET" | \
  curl -s -K - -d grant_type=client_credentials https://zap.mutual.solutions/oauth/token
# {"access_token": "zat_...", "token_type": "Bearer", "expires_in": 3600, "scope": "zap"}

/v1/... 요청에 API 키처럼 Authorization: Bearer <access_token>으로 보냅니다. 401을 받으면 새 토큰을 받으세요.

OAuth 엔드포인트는 아래 에러 표가 아니라 OAuth 에러 형식({"error": "invalid_grant", "error_description": "..."})으로 답합니다. /v1이나 /mcp의 401에는 WWW-Authenticate: Bearer resource_metadata="..."가 붙습니다. 로그인 데이터: 이메일 주소, 제공자 계정 ID, 토큰의 해시. Zap! 서버와 매일 만드는 백업 사본에 보관하며, 백업 사본은 14일 뒤 삭제됩니다 (개인정보 처리방침).

5. 에러

모든 에러는 고정된 코드와, 무엇을 고치면 되는지 한 문장으로 알려주는 메시지를 담은 JSON입니다: {"error": "<code>", "message": "..."}. 실패한 작업은 상태 조회 결과에 {"error": {"code": "...", "message": "..."}}로 나타납니다. 코드는 바뀌지 않으며, 메시지는 더 알기 쉽게 고쳐질 수 있습니다(메시지는 영어입니다).

작업은 완전히 라우팅된 보드를 돌려주거나 실패하거나 둘 중 하나입니다. 부분 결과는 없습니다.

점검 중(보통 1분 이내)에는 Zap! 앞단의 네트워크가 JSON 대신 HTML 페이지로 502를 돌려줄 수 있습니다. 1분쯤 기다렸다가 다시 시도하세요. zap.py는 상태 조회와 다운로드를 스스로 다시 시도합니다.

error code: 1010이라는 글자와 함께 오는 403은 Zap!이 아니라 Zap! 앞단의 네트워크(Cloudflare)가 보낸 것입니다. 아무 User-Agent 헤더나 보내세요(예: my-agent/1.0). Python 기본 urllib이 보내는 기본 이름은 앞단에서 막힙니다.

6. 한도

7. 데이터 처리

개인정보처리방침(English)과 이용약관(영문)이 적용됩니다. 요약하면:

• 보내주신 파일은 해당 작업을 라우팅하는 데만 씁니다.
• 업로드 파일은 작업이 끝나는 즉시 삭제합니다. 라우팅된 보드는 7일 뒤에 삭제되며, DELETE /v1/jobs/{id}로 바로 지울 수도 있습니다.
• 작업 기록(id, 시각, 상태, 요약 수치)은 보드 데이터 없이 2년간 남깁니다.
• 서면 동의 없이 보드를 저희 소프트웨어의 학습이나 개발에 쓰지 않습니다. consent_training=true는 의사를 기록할 뿐이며, 그것만으로 서면 동의가 되지는 않습니다.
• 요청 로그에는 시각, IP 주소, 키 id, 요청 경로, 상태, 크기만 남습니다. 보드 내용, 파일 이름, 키, 피드백 내용은 절대 남기지 않습니다.
• API 키는 단방향 해시로만 저장합니다. 키를 잃어버리면 새로 발급해 드립니다.
• 피드백. 직접, 또는 동의하신 AI 에이전트를 통해 피드백을 보내시면, 보내신 글과 첨부하신 보드 그림만 Zap! 개선에 씁니다. 이것은 작업 id, 그리고 저희가 이미 보관하는 요약 수치와 연결되며, 보드 파일은 보관하지도 쓰지도 않습니다. 피드백은 Zap! 팀이 AI 도구의 도움을 받아 읽습니다. 여쭙지 않고 공개하거나 인용하지 않고, 판매하지 않으며, AI 모델 학습에 쓰지 않습니다. 연락을 허락하신 경우에만 답장을 드립니다. 최대 2년, 또는 hello@mutual.solutions로 삭제를 요청하실 때까지 보관하며, 백업 사본은 14일 안에 만료됩니다. 개인 정보나 기밀은 빼고 보내주세요.
• 작업 기록, 키 해시, 피드백, 로그인 계정(보드 데이터 없음)은 매일 서비스와 같은 클라우드 리전의 암호화된 비공개 저장소에 백업하며, 각 백업 사본은 14일 뒤 삭제합니다.

8. 이 (아직) 하지 않는 것

• 부품 배치: 부품은 배치하신 자리에 그대로 있습니다.
• 회로도 검사.
• 차동쌍 스큐 외의 길이 매칭, 임피던스 보장.
• 제조 승인(sign-off). 제작 전에 모든 보드를 검토하고 직접 DRC를 돌리세요.

9. 피드백

무엇을 그대로 썼는지, 무엇을 고쳤는지, 무엇을 버렸는지 알려주세요. 짧은 메모는 언제든 환영합니다. 보내는 방법은 두 가지입니다.

• AI 에이전트나 명령줄로. Zap!을 쓰는 에이전트에게 Zap!이나 결과에 대한 생각을 말씀하시면, 에이전트가 저희에게 보낼지 묻고 보낼 문구 그대로와 작업 id를 보여드린 뒤, 동의하실 때만 보냅니다. 명령줄: python3 zap.py feedback "U3 근처 라우팅이 지저분해요" --job JOB_ID는 문구를 보여주고 먼저 묻습니다. API: 키와 함께 POST /v1/feedback에 JSON {"message": "...", "user_approved": true, "job_id": "...", "kind": "problem", "contact_ok": true}를 보내세요. kind는 praise, problem, idea, other 중 하나이고, contact_ok: true면 계정 이메일로 답장을 드릴 수 있습니다. 응답은 201 {"id", "received_at"}입니다. 최대 4,000자, 키당 UTC 하루 20건이며, 보드 파일은 이 방법으로 보내지 않습니다.
• 그 지점의 그림. 피드백이 보드의 한 곳에 관한 것이면, 에이전트가 그 영역만 담은 그림(최대 40 mm 정사각형, 보고서의 빠진 연결과 디자인 룰 오류 표시)을 보여드리고, 동의하시면 첨부합니다: POST /v1/jobs/{id}/snapshot에 {"x_mm": X, "y_mm": Y, "size_mm": 20}을 보낸 뒤 피드백의 "snapshot_ids"에 넣습니다(최대 3장). 명령줄: python3 zap.py snapshot JOB_ID --at 93.5,69.5로 그림을 저장하고, zap.py feedback "..." --job JOB_ID --snapshot ID로 첨부합니다. 첨부하지 않은 그림은 24시간 뒤 삭제되며, 원하지 않으시면 바로 지웁니다(DELETE /v1/snapshots/{id}.png). 보드 전체는 절대 아닙니다.
• 이메일로 hello@mutual.solutions에 보내주세요. 수정한 .kicad_pcb도 보내주실 경우, Zap! 개선에 써도 되는지 같은 메시지에 적어주세요. 서면 동의가 없으면 답변에만 사용하고 그 뒤 삭제합니다.

AI 에이전트에게. 사용자가 Zap!이나 라우팅 결과에 대해 의견(마음에 든 점, 문제, 바라는 점)을 말할 때마다, Zap! 팀에 보낼지 한 번 물어보세요. 물을 때는 어떻게 되는지 부풀리거나 줄이지 말고 짧은 한 문장으로 알려주세요. 예: "이 내용을 Zap! 팀에 보낼까요? 이 글(그림이 있으면 그림도)만 Zap! 개선에 쓰이고 보드 파일은 쓰이지 않으며, 삭제를 요청할 수 있습니다." 보낼 문구 그대로(사용자의 말, 또는 사용자가 동의한 요약)와 작업 id를 보여주세요. 동의할 때만 send_feedback이나 POST /v1/feedback으로 보내세요. 거절하면 그 세션에서는 다시 묻지 마세요. 피드백이 보드의 한 곳에 관한 것이면, 보고서의 문제 위치로 맞춘 그 영역만의 그림(board_snapshot 또는 POST /v1/jobs/{id}/snapshot)을 첨부할지 제안하세요. 보내기 전에 그림을 사용자에게 보여주고, 동의할 때만 첨부하세요. 원하지 않으면 그림을 지우세요(delete_snapshot). 보드 전체는 절대 안 됩니다. 사용자가 동의하지 않은 보드 파일이나 개인 정보는 절대 넣지 마세요.