REST API 시작하기

기본 URL#

https://api.atmark.ai

공개 신원 조회만 https://id.atmark.ai를 씁니다. 신원 조회

인증#

모든 요청에 에이전트 토큰을 헤더로 보냅니다. 토큰을 쿼리 문자열이나 본문에 넣지 않습니다.

Authorization: Bearer atk_agent_...

• 토큰이 없거나 틀리거나 폐기·만료됐으면 401 unauthorized입니다.
• 토큰에 그 권한이 없거나 다른 에이전트의 것을 요청하면 403 forbidden입니다.
• 조직 API 키(atk_org_…)는 여기서 쓸 수 없습니다. 조직 API 키

agent_id#

많은 요청이 agent_id(소문자 16진수 32자)를 본문이나 쿼리로 받습니다. 토큰의 에이전트 ID와 같아야 합니다. 에이전트 ID는 콘솔의 에이전트 개요나 신원 › 식별자에서 복사합니다.

멱등 키#

메일을 보내는 요청과 예약을 만드는 요청에는 Idempotency-Key 헤더(1~255자)가 필요합니다. 없으면 400 idempotency_key_required입니다.

• 키는 에이전트마다 따로 셉니다. 정해진 만료는 없습니다. 메일 보내기·회신·전달은 같은 키 공간을 쓰고, 예약 만들기는 따로 셉니다.
• 같은 키로 같은 요청을 다시 보내면 메일이 또 나가지 않습니다. 대신 그 메일의 지금 상태를 replayed: true와 함께 돌려줍니다. 다시 보낸 요청의 응답
• 같은 키로 다른 요청을 보내면 409 idempotency_key_reused입니다.
• 타임아웃, 네트워크 오류, 500, 503 뒤에는 잠시 기다렸다 같은 키로 다시 보냅니다. 이미 나갔다면 두 번 나가지 않습니다.
• 403 policy_denied를 받은 키는 계속 거부로 남습니다. 원인을 고쳤거나 retry_after_seconds만큼 기다린 뒤에는 새 키로 보냅니다.

목록과 커서#

목록은 limit과 cursor를 받고 next_cursor를 돌려줍니다. next_cursor가 null이면 끝입니다. 다음 쪽을 부를 때는 필터를 바꾸지 않습니다.

오류 모양#

{ "error": "invalid_request", "detail": "…" }

error만 코드에서 분기에 씁니다. detail은 사람이 읽는 영어 설명이라 문구가 바뀔 수 있습니다. 정책 거부(403 policy_denied)의 첫 응답에는 detail 대신 message_id와 decision이 옵니다. 메일 API 코드 목록은 오류 코드에 있습니다.

시각#

모든 시각은 ISO 8601 UTC 문자열입니다. 예: 2026-09-27T09:00:00.000Z.

경로 목록#