본문으로 건너뛰기

API 레퍼런스 개요

MIRI API는 AI 기반 이력서-채용공고 매칭 분석을 위한 RESTful 엔드포인트를 제공합니다. 모든 API 엔드포인트는 요청, 응답 및 오류 처리에 대해 일관된 패턴을 따릅니다.

Base URL​

https://open-miri-api.axistant.org/public/v1

사용 가능한 API​

핵심 API​

API설명사용 사례
Analysis API단일 이력서-채용공고 매칭 분석개별 후보자에 대한 실시간 분석
Batch API여러 분석을 동시에 처리채용 캠페인을 위한 대량 처리

관리 API​

API설명사용 사례
웹훅 서명 검증서명 검증 및 재시도 처리실시간 알림 수신

모니터링 API​

API설명사용 사례
Health Check서비스 상태 확인모니터링 및 알림

요청 형식​

헤더​

모든 요청에는 다음 헤더가 포함되어야 합니다:

Miri-Api-Key: miri_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Accept: application/json

요청 본문​

요청 본문은 JSON으로 전송됩니다. 예시는 다음과 같습니다.

{
  "resumeData": {
    "type": "pdf",
    "content": "base64-encoded PDF"
  },
  "jobPostingData": {
    "type": "html",
    "content": "<h1>Senior Backend Engineer</h1><p>서비스 설계...</p>"
  },
  "options": {
    "webhook": {
      "url": "https://partner.example.com/webhooks/analysis",
      "secret": "your-hmac-secret"
    }
  }
}
콘텐츠 인코딩

text/html 항목은 UTF-8 텍스트를 사용하고, PDF/DOCX 파일은 base64로 인코딩하세요.

응답 형식​

성공 응답​

성공 응답에는 success, data, 선택적인 message/metadata가 포함됩니다.

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "links": {
      "self": "/public/v1/analyses/550e8400-e29b-41d4-a716-446655440000"
    }
  },
  "message": null,
  "code": "SUCCESS",
  "metadata": null
}

오류 응답​

오류 응답은 일관된 형식을 따르며 선택적 메타데이터를 포함합니다:

{
  "success": false,
  "data": null,
  "message": "요청 본문이 유효하지 않습니다",
  "code": "VAL001",
  "metadata": {
    "field": "resumeData.content",
    "error": "필수 필드가 누락되었습니다"
  }
}

오류 코드​

코드메시지HTTP 상태
INVALID_API_KEYMiri-Api-Key 헤더 누락 또는 형식 오류401
AUTH001유효하지 않은 API 키401
AUTH003API 키가 정지됨403
VAL001잘못된 요청 형식400
VAL002필수 필드 누락400
VAL003잘못된 필드 값400
VAL004요청 크기 제한 초과400
BUS002크레딧 부족402
SVC001서비스 일시적으로 사용 불가503
SVC002서킷 브레이커 열림503
SVC003종속성 타임아웃503
INT001내부 서버 오류500
INTERNAL_ERRORAPI 키 필터에서 발생한 내부 오류500
NOT001분석을 찾을 수 없음404
NOT003고객을 찾을 수 없음404
NOT000리소스를 찾을 수 없음404

metadata 필드는 선택적으로 채워지며 다음과 같이 활용됩니다.

  • 유효성 검사 오류(VAL001~VAL003): 잘못된 field, 입력 값, 필요한 경우 validValues를 포함합니다.
  • 크레딧 부족(BUS002): required, available, purchaseUrl 정보를 제공해 즉시 충전할 수 있도록 안내합니다.
  • 서비스 오류(SVC001~SVC003): 응답 헤더와 동일한 retryAfter 값을 전달하며, 회로 차단기 경로는 service 키로 영향을 받은 영역을 명시합니다.
  • 예상치 못한 오류(INT001): 전달받은 X-Request-ID를 메타데이터에 반영해 지원 요청 시 추적할 수 있습니다.
  • 인증 실패: 필터에서 즉시 거절되는 경우 INVALID_API_KEY(필터 예외 발생 시 INTERNAL_ERROR) 코드와 단순 메시지만 반환되며, 컨트롤러 단계에서 실패하면 AUTH001 코드가 사용됩니다.

참고: 유효성 검증 실패 경로(예: JSON 파싱 단계 vs 필드 검증 단계)에 따라 동일한 문제라도 VAL001(잘못된 요청) 또는 VAL003(잘못된 필드 값)으로 분기될 수 있습니다.

요청 제한 안내: 서비스 앞단의 트래픽 가드가 IP 기준 5분당 2,500건의 호출을 감시합니다. 한도를 초과하면 403 Forbidden이 반환되지만 응답 본문은 단순하며 추가적인 레이트 리미트 헤더는 포함되지 않습니다.

HTTP 상태 코드​

상태 코드설명
200 OK요청 성공
201 Created리소스 생성 성공
202 Accepted처리를 위해 요청 수락됨
204 No Content요청 성공, 반환할 내용 없음
400 Bad Request잘못된 요청 형식 또는 매개변수
401 Unauthorized유효하지 않거나 누락된 API 키
402 Payment Required크레딧 부족
403 Forbidden접근 거부 (레이트리밋 포함)
404 Not Found리소스를 찾을 수 없음
500 Internal Server Error서버 오류
503 Service Unavailable서비스 일시적으로 사용 불가

데이터 타입​

콘텐츠 타입​

지원되는 문서 형식:

  • text - 일반 텍스트 콘텐츠

상태 값​

분석 상태​

  • QUEUED - 분석이 처리 대기 중
  • PROCESSING - 분석이 처리 중
  • COMPLETED - 분석이 성공적으로 완료됨
  • FAILED - 분석 실패

배치 상태​

  • QUEUED - 배치가 시작 대기 중
  • PROCESSING - 배치가 처리 중
  • COMPLETED - 모든 항목 처리 완료
  • PARTIAL - 일부 항목 성공, 일부 실패
  • FAILED - 배치 처리 실패

페이지네이션​

목록 엔드포인트는 쿼리 매개변수를 사용한 페이지네이션을 지원합니다:

GET /public/v1/webhooks?page=0&size=20

매개변수​

매개변수타입기본값설명
pageinteger0페이지 번호 (0부터 시작)
sizeinteger20페이지당 항목 수 (최대: 100)
sortstringcreatedAt,desc정렬 필드 및 방향

응답​

{
  "success": true,
  "data": {
    "content": [...],
    "page": {
      "size": 20,
      "number": 0,
      "totalElements": 150,
      "totalPages": 8,
      "first": true,
      "last": false,
      "empty": false
    }
  },
  "message": "목록을 성공적으로 조회했습니다"
}

요청 제한​

요청 제한은 애플리케이션 앞단에서 관리됩니다. 기본 한도는 IP 주소 기준 5분당 2,500건이며 한도를 초과하면 403 Forbidden이 반환됩니다. 추가적인 레이트 리미트 헤더가 없으므로 사용량 대시보드(또는 자체 지표)를 활용해 호출량을 모니터링하고, 클라이언트 측 큐/백오프로 버스트를 제어하세요.

멱등성​

리소스를 생성하는 POST 요청의 경우, 멱등성 키를 포함하여 멱등성을 보장할 수 있습니다:

X-Idempotency-Key: unique-request-id-123

24시간 이내에 동일한 멱등성 키를 가진 중복 요청에 대해 동일한 응답이 반환됩니다.

CORS 지원​

브라우저 요청은 플랫폼 허용 목록에 등록된 출처에서만 수락됩니다. 기본값에는 MIRI 콘솔 도메인과 로컬 개발 도메인이 포함됩니다. 운영 환경에서 추가 출처가 필요하면 지원팀에 등록을 요청하세요.

허용된 출처에서 요청이 수락되면 응답 헤더에는 다음 정보가 포함됩니다.

Access-Control-Allow-Origin: https://등록된-출처.example
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: *
Access-Control-Expose-Headers: Authorization, X-New-Access-Token, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Access-Control-Allow-Credentials: true

웹훅​

실시간 알림을 받기 위해 웹훅을 구성하세요:

  1. 웹훅 엔드포인트 등록
  2. 웹훅 서명 검증
  3. 웹훅 이벤트 처리

전송은 2초 간격으로 최대 3회까지 재시도되며 모두 실패하면 대상 URL을 수정한 뒤 요청을 다시 실행해야 합니다. 서명 검증 방법은 웹훅 서명 검증을 참고하세요.

다음 단계​

최종 수정: 에