점검 진행 중 — 나중에 다시 시도해 주세요.

🕊️

HATO API

비둘기 우체국

📘 매뉴얼 로그인
07 / 내 도구와 연결하기

API 레퍼런스

Letterflow 목록과 정의를 조회하고 실행을 제출하고 상태를 확인하며 각 단계의 지역 입력과 출력을 살펴볼 수 있습니다.

키를 사용하기 전에 권한을 선택하세요

Tinkerer 키는 Letterbox 항목 읽기, 고정, 삭제에 사용할 수 있습니다. Aspiring에서는 해당 범위를 선택하면 저장된 정의 읽기, 실행 제출, 상태 조회도 가능합니다. 새 키의 기본 권한은 Letterbox 읽기만이며, 실행 권한만으로 상태나 결과를 조회할 수는 없습니다.

개요

인증

설정 → 연동 API 키에서 API 키를 생성하세요. Authorization 헤더에 토큰을 포함해야 합니다:

키마다 리소스와 작업 권한을 선택하세요. 새 키는 레터박스 읽기만 허용하며 실행, 상태 확인, 고정, 삭제에는 각각 별도의 권한이 필요합니다.

Authorization: Bearer hato_live_<token>

속도 제한 및 캐싱

API 키는 발신 IP와 관계없이 분당 30회까지 요청할 수 있습니다. 메타데이터는 ETag 조건부 요청을 지원합니다. 리전 접근 URL은 5분 이내에 만료되며 콘텐츠 보관 기간도 적용됩니다.

오류 형식

오류는 오류 코드와 상세 메시지가 포함된 표준 JSON 객체로 반환됩니다:

{"error": {"code": "unauthorized", "message": "A valid Bearer API key is required."}}

저장된 정의

limit와 cursor로 내 Letterflow 목록을 페이지 단위로 조회합니다. 상세 정보에는 메타데이터, 준비 상태, 지역 입력의 서명된 링크가 포함됩니다. 개인 키와 계정 자격 증명은 제외됩니다.

엔드포인트API 권한
GET /api/v1/letterflows/
GET /api/v1/letterflows/{id}/		letterflows:read

실행 요청 및 상태 확인

빈 JSON 객체를 POST하면 저장한 Letterflow가 즉시 실행됩니다. 실행마다 새로운 Idempotency-Key가 필요합니다. 같은 키를 재전송하면 같은 실행을 반환합니다. 입력 재정의와 API 예약은 지원하지 않습니다.

엔드포인트API 권한
POST /api/v1/letterflows/{id}/runs/letterflows:run
GET /api/v1/runs/{uuid}/runs:read

새 실행은 202와 Location 폴링 URL을 반환하며 멱등성 재요청은 200을 반환합니다. 상태는 waiting, queued, running, completed, failed입니다. waiting은 계정 용량이 아직 예약되지 않은 상태이고 queued는 실행이 승인되어 리전 실행을 기다리는 상태입니다. letterbox_url이 제공되면 해당 URL을 확인하세요. 모든 제출에 실행 준비 상태와 플랜 한도가 적용됩니다.

실행 폴링에는 queue_position, wait_reason, admitted_at이 포함됩니다. 대기열이 가득 차면 429와 error.code=queue_full을 반환합니다. 수락된 멱등성 키는 취소 후에도 항상 같은 실행을 반환하므로 새 배달에는 새 키를 사용하세요.

배달 대기열 → 
curl -X POST -H "Authorization: Bearer $HATO_API_KEY" \
  -H 'Idempotency-Key: example-run-001' -H 'Content-Type: application/json' \
  --data '{}' 'https://hato-api.example/api/v1/letterflows/7/runs/'

Letterflow 단계 살펴보기

단계 경로에는 value1과 같은 사용자 정의 컴포넌트 ID를 사용합니다. ID는 대소문자를 구분하며 고정된 실행 스냅샷에서 찾습니다. 이후 이름을 변경해도 이전 실행에 대한 접근은 유지됩니다.

GET /api/v1/letterbox/{id}/steps/
GET /api/v1/letterbox/{id}/steps/{step_id}/
GET /api/v1/letterbox/{id}/steps/{step_id}/input/
GET /api/v1/letterbox/{id}/steps/{step_id}/output/
GET /api/v1/letterbox/{id}/steps/{step_id}/request-headers/
GET /api/v1/letterbox/{id}/steps/{step_id}/request-body/
GET /api/v1/letterbox/{id}/steps/{step_id}/response-headers/
GET /api/v1/letterbox/{id}/steps/{step_id}/response-body/
GET /api/v1/letterbox/{id}/steps/{step_id}/request-metadata/
GET /api/v1/letterbox/{id}/steps/{step_id}/value/

단계 조회에는 letterbox:read가 필요하며 지정 리전으로 리다이렉트됩니다. 실행을 시도한 컴포넌트가 실행 순서로 표시된 후 건너뛴 컴포넌트가 표시됩니다. 건너뛴 입력은 읽을 수 있지만 생성되지 않은 출력은 404를 반환합니다. 저장된 결과는 다시 평가하지 않습니다.

밸류 출력은 텍스트이며 조건 출력은 불리언입니다. 큰 밸류는 result_url을 제공하고, 레터 단계는 기록된 요청 및 응답 아티팩트 링크를 제공합니다. 만료된 콘텐츠는 410을 반환합니다.

Letter 단계 메타데이터에는 기록된 http_version이 있으면 포함됩니다. 이는 클라이언트의 선호 설정이 아닌 최종 응답에서 협상된 프로토콜입니다.

Bearer 키는 Hub에만 보내세요. 리전 접근 URL은 API 키를 전달하지 않는 별도의 요청으로 조회하세요.

Letterbox 목록은 letterflow_id와 run_id로 필터링할 수 있습니다. source_type(letter, condition, value, email)은 마지막 구성 요소의 결과 유형입니다.

목록

GET /api/v1/letterbox/
레터박스 항목 목록 조회

최신순으로 정렬된 레터박스 응답 메타데이터의 커서 페이지네이션 목록을 조회합니다.

헤더
Authorization필수 Bearer hato_live_...
If-None-Match 304 조건부 캐시 검증을 위한 선택적 ETag.
쿼리 매개변수
매개변수설명
limitinteger 반환할 레코드 수(1~100, 기본값: 50).
cursorstring 이전 응답에서 반환된 페이지네이션 커서.
sinceISO-8601 지정된 일시 이후에 전송된 항목 필터링(예: 2026-08-01T00:00:00Z).
untilISO-8601 지정된 일시 이전에 전송된 항목 필터링.
letter_idinteger 특정 Letter ID로 항목 필터링.
source_typestring 최종 결과 유형으로 필터링합니다: letter, condition, value.
status_codeinteger HTTP/FTP 응답 코드로 필터링(예: 200, 404, 500).
pinnedboolean 고정 상태('true' 또는 'false')로 필터링.
응답
200 OK 항목 배열과 선택적 next_cursor를 반환합니다.
400 Bad Request 매개변수 또는 커서 형식이 잘못되었습니다.
401 Unauthorized Bearer API 키가 누락되었거나 유효하지 않습니다.
cURL 
curl -H "Authorization: Bearer $HATO_API_KEY" \
     "https://hato-api.example/api/v1/letterbox/?limit=20&pinned;=true"
응답 (200 OK) 
{
  "data": [
    {
      "id": 42,
      "letterflow_id": 7,
      "letterflow_name": "Health Check",
      "source_type": "letter",
      "run_id": null,
      "steps_url": null,
      "request": {
        "method": "GET"
      },
      "response": {
        "status_code": 200
      },
      "duration_ms": 142,
      "sent_at": "2026-08-28T14:30:00+00:00",
      "request_sent_at": "2026-08-28T14:30:00.010000+00:00",
      "response_received_at": "2026-08-28T14:30:00.152000+00:00",
      "is_pinned": true,
      "bodies_pruned": false,
      "error_message": "",
      "region": "au",
      "spoke_id": "spoke-au-1",
      "artifact_available": true,
      "request_headers_url": "https://spoke-au.example/artifacts/...",
      "request_body_url": null,
      "response_headers_url": "https://spoke-au.example/artifacts/...",
      "response_body_url": "https://spoke-au.example/artifacts/..."
    }
  ],
  "next_cursor": "eyJzZW50X2F0IjoiMjAyNi0wOC0yOFQxNDozMDowMCIsImlkIjo0Mn0"
}
DELETE /api/v1/letterbox/
고정되지 않은 모든 항목 비우기

고정하지 않은 Letterbox 결과를 모두 삭제하고 관련 리전 아티팩트도 삭제합니다. Spoke를 일시적으로 사용할 수 없으면 정리 작업을 재시도 큐에 넣습니다.

응답
204 No Content 고정되지 않은 모든 항목이 성공적으로 삭제되었습니다.
401 Unauthorized Bearer API 키가 누락되었거나 유효하지 않습니다.
cURL 
curl -X DELETE \
     -H "Authorization: Bearer $HATO_API_KEY" \
     "https://hato-api.example/api/v1/letterbox/"
GET /api/v1/letterbox/{id}/
항목 메타데이터 조회

ID를 기반으로 단일 레터박스 응답의 전체 메타데이터(새로 서명된 리전 아티팩트 URL 포함)를 조회합니다.

URI 매개변수
idinteger필수 레터박스 항목의 고유 ID.
응답
200 OK 항목 메타데이터가 성공적으로 반환되었습니다.
404 Not Found 항목이 존재하지 않거나 다른 사용자에게 속해 있습니다.
cURL 
curl -H "Authorization: Bearer $HATO_API_KEY" \
     "https://hato-api.example/api/v1/letterbox/42/"
응답 (200 OK) 
{
  "data": {
    "id": 42,
    "letterflow_id": 7,
    "letterflow_name": "Health Check",
    "source_type": "letter",
    "run_id": null,
    "steps_url": null,
    "request": {
      "method": "GET"
    },
    "response": {
      "status_code": 200
    },
    "duration_ms": 142,
    "sent_at": "2026-08-28T14:30:00+00:00",
    "request_sent_at": "2026-08-28T14:30:00.010000+00:00",
    "response_received_at": "2026-08-28T14:30:00.152000+00:00",
    "is_pinned": false,
    "bodies_pruned": false,
    "error_message": "",
    "region": "au",
    "spoke_id": "spoke-au-1",
    "artifact_available": true,
    "request_headers_url": "https://spoke-au.example/artifacts/read?token=...",
    "request_body_url": null,
    "response_headers_url": "https://spoke-au.example/artifacts/read?token=...",
    "response_body_url": "https://spoke-au.example/artifacts/read?token=..."
  }
}
PATCH /api/v1/letterbox/{id}/
항목 고정 또는 고정 해제

레터박스 항목을 고정하거나 고정 해제합니다. 고정 시 응답 본문이 만료 및 FIFO 용량 삭제로부터 보호됩니다.

요청 본문
항목타입설명
is_pinned필수 boolean 고정하려면 true, 고정을 해제하려면 false로 설정합니다.
응답
200 OK 고정 상태가 성공적으로 업데이트되었습니다.
400 Bad Request 잘못된 JSON 페이로드이거나 용량 한도에 도달했습니다(용량이 가득 찼을 때 최소 1개의 응답은 고정되지 않은 상태여야 합니다).
404 Not Found 항목이 존재하지 않습니다.
cURL 
curl -X PATCH \
     -H "Authorization: Bearer $HATO_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"is_pinned": true}' \
     "https://hato-api.example/api/v1/letterbox/42/"
응답 (200 OK) 
{
  "data": {
    "id": 42,
    "letterflow_id": 7,
    "letterflow_name": "Health Check",
    "source_type": "letter",
    "run_id": null,
    "steps_url": null,
    "request": {
      "method": "GET"
    },
    "response": {
      "status_code": 200
    },
    "duration_ms": 142,
    "sent_at": "2026-08-28T14:30:00+00:00",
    "request_sent_at": "2026-08-28T14:30:00.010000+00:00",
    "response_received_at": "2026-08-28T14:30:00.152000+00:00",
    "is_pinned": true,
    "bodies_pruned": false,
    "error_message": "",
    "region": "au",
    "spoke_id": "spoke-au-1",
    "artifact_available": true,
    "request_headers_url": "https://spoke-au.example/artifacts/read?token=...",
    "request_body_url": null,
    "response_headers_url": "https://spoke-au.example/artifacts/read?token=...",
    "response_body_url": "https://spoke-au.example/artifacts/read?token=..."
  }
}
DELETE /api/v1/letterbox/{id}/
단일 항목 삭제

단일 응답 레코드를 영구적으로 삭제하고 리전 Spoke에 저장된 아티팩트 정리를 트리거합니다.

URI 매개변수
idinteger필수 삭제할 레터박스 항목의 고유 ID.
응답
204 No Content 항목이 영구적으로 삭제되었습니다.
404 Not Found 항목이 존재하지 않습니다.
cURL 
curl -X DELETE \
     -H "Authorization: Bearer $HATO_API_KEY" \
     "https://hato-api.example/api/v1/letterbox/42/"
GET /api/v1/letterbox/{id}/{artifact}/
아티팩트 스트림 다운로드

유효 시간이 짧은 리전 URL로 리디렉션합니다. Bearer 키는 Hub에 보내고 리전 Location은 키를 전달하지 않는 별도 요청으로 가져오세요. 콘텐츠 접근 권한에는 보관 기간과 소유권 확인이 적용됩니다.

URI 매개변수
idinteger필수 레터박스 항목 ID.
artifactstring필수 다음 중 하나: request-headers, request-body, response-headers, response-body.
응답
302 Found 서명된 Spoke 직접 URL로 리다이렉트합니다(5분간 유효).
404 Not Found 아티팩트가 없거나 정리되었거나 존재하지 않습니다.
cURL(두 번의 요청) 
curl -sS -D - -o /dev/null -H "Authorization: Bearer $HATO_API_KEY" \
     "https://hato-api.example/api/v1/letterbox/42/response-body/"

curl -o response_payload.json "REGIONAL_LOCATION_URL"
리다이렉트 헤더 (302 Found) 
HTTP/1.1 302 Found
Location: https://spoke-au.example/artifacts/read?token=ey...
Cache-Control: private, no-store

Directory

유료 연동 키는 directory:read를 명시적으로 선택하여 변수 목록과 지역 값 URL을 조회할 수 있습니다. 비밀 값도 포함하는 권한이며 자동으로 부여되지 않습니다. Directory 변경은 대시보드에서만 가능합니다.

GET /api/v1/directory/?region=au
GET /api/v1/directory/{id}/