API 레퍼런스

AgentSend REST API. 모든 요청과 응답은 JSON을 사용합니다. 기본 URL: https://api.agentsend.io.

개요

AgentSend API는 에이전트에게 수신함, 메시지, 스레드, 웹훅, 도메인, 첨부파일, 계정 설정에 대한 프로그래밍 방식 액세스를 제공하는 REST API입니다. 모든 요청과 응답 본문은 JSON입니다.

모든 API 엔드포인트는 다음 기본 URL에서 사용할 수 있습니다:

base url

https://api.agentsend.io

ⓘ

로컬 개발의 경우 서버를 로컬에서 실행할 때 http://localhost:3000에서 API를 사용할 수 있습니다.

인증

AgentSend API는 두 가지 인증 방법을 지원합니다. 요청당 하나만 필요합니다.

Bearer 토큰

API 키를 Authorization 헤더에 Bearer 토큰으로 전달합니다. 서버 측 요청에 권장되는 방법입니다.

curl

curl https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>"

API 키 헤더

또는 x-api-key 헤더에 API 키를 직접 전달합니다.

curl

curl https://api.agentsend.io/inboxes \
  -H "x-api-key: <your-api-key>"

⚠

API 키는 비밀로 유지하세요. 클라이언트 측 코드에 노출하거나 버전 관리에 커밋하지 마세요. 환경 변수를 사용해 애플리케이션에 전달하세요.

요청 형식

요청 본문을 JSON으로 보내고 본문이 있는 모든 요청에 Content-Type: application/json 헤더를 포함하세요.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Support Agent"}'

페이지네이션

목록을 반환하는 엔드포인트는 페이지네이션을 위해 limit와 offset 쿼리 파라미터를 지원합니다. 기본 limit은 20입니다.

파라미터	Type	기본값	설명
`limit`	integer	`20`	반환할 최대 항목 수. 최대 100.
`offset`	integer	`0`	결과를 반환하기 전에 건너뛸 항목 수.

모든 목록 응답에는 data 배열과 일치하는 모든 레코드의 total 수가 포함됩니다:

json — paginated response

{
  "data": [ /* array of objects */ ],
  "total": 142
}

다음 페이지를 가져오려면 offset을 limit 값만큼 증가시킵니다. 예를 들어 페이지 크기 20의 3페이지를 얻으려면: ?limit=20&offset=40.

오류 처리

오류는 기계가 읽을 수 있는 code, 사람이 읽을 수 있는 message, HTTP status를 포함하는 error 객체가 있는 JSON 본문을 반환합니다.

json — error response

{
  "error": {
    "code": "INBOX_NOT_FOUND",
    "message": "No inbox found with that ID.",
    "status": 404
  }
}

API가 반환하는 일반적인 HTTP 상태 코드:

상태	의미
`400`	Bad Request — 요청 본문에 필수 필드가 없거나 잘못된 값이 포함되어 있습니다.
`401`	Unauthorized — API 키가 제공되지 않았거나 유효하지 않습니다.
`403`	Forbidden — API 키에 이 작업을 수행할 권한이 없습니다.
`404`	Not Found — 요청한 리소스가 존재하지 않습니다.
`409`	Conflict — 리소스가 이미 존재하거나 요청이 현재 상태와 충돌합니다.
`429`	Too Many Requests — 속도 제한을 초과했습니다. 잠시 후 재시도하세요.
`500`	Internal Server Error — AgentSend 측에서 문제가 발생했습니다.

속도 제한

모든 API 엔드포인트는 플랫폼 안정성을 보호하기 위해 속도 제한이 적용됩니다. 제한을 초과하면 API는 429 Too Many Requests 응답을 반환합니다.

모든 API 응답에는 사용량을 추적할 수 있는 속도 제한 헤더가 포함됩니다:

헤더	설명
`X-RateLimit-Limit`	현재 창에서 허용된 최대 요청 수.
`X-RateLimit-Remaining`	현재 창에 남은 요청 수.
`X-RateLimit-Reset`	속도 제한 창이 재설정되는 Unix 타임스탬프.

💡

429 응답 후 재시도 시 지수 백오프를 사용하세요. 추가 요청을 보내기 전에 X-RateLimit-Reset이 나타내는 시간을 기다리세요.

멱등성

POST 요청은 중복 리소스를 생성하지 않고 안전하게 요청을 재시도할 수 있도록 Idempotency-Key 헤더를 포함할 수 있습니다. 멱등성 창 내에 동일한 멱등성 키로 요청이 수신되면 새 리소스를 만드는 대신 원본 응답이 반환됩니다.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-request-id-abc123" \
  -d '{"displayName": "Support Agent"}'