API 문서

Regunow API는 HTTPS, Bearer 인증 및 버전 접두사 /api/v1를 사용합니다. 계정 없이 이 문서를 읽을 수 있습니다. API 요청에는 활성 Pro 이용 권한과 현재 정책에 대한 동의가 필요합니다.

1. Regunow에 로그인하고 설정 → API 키에서 키를 만드세요.
2. 비밀 키를 안전하게 보관하세요. 키를 만들 때 한 번만 표시됩니다.
3. 호스트와 키를 설정한 후 백엔드 또는 신뢰할 수 있는 자동화에서 첫 질문을 보내세요.

# Use your Regunow host and a key from Settings → API Keys.
export REGUNOW_BASE_URL="https://YOUR_REGUNOW_HOST"
export REGUNOW_API_KEY="YOUR_API_KEY"

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-question-001" \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Which EU product-safety obligations apply to a connected consumer device?"
    }],
    "mode": "jurisdiction",
    "jurisdiction": "eu"
  }'

답변은 output.content에 있습니다. 응답에는 출처 참조와 청구된 크레딧도 포함됩니다. 이 요청은 크레딧을 사용합니다. 새 질문마다 새 멱등성 키를 사용하세요.

// Node.js: set REGUNOW_BASE_URL and REGUNOW_API_KEY in your environment.
// Generate one key per operation; keep it unchanged when retrying that operation.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();
const response = await fetch(
  process.env.REGUNOW_BASE_URL + "/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.REGUNOW_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: "Summarize EU product-safety obligations." }],
      mode: "jurisdiction",
      jurisdiction: "eu",
    }),
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error.code + ": " + result.error.message);
}
console.log(result.output.content);

모든 요청에서 HTTP Authorization 헤더에 API 키를 보내세요. URL, 쿠키 또는 요청 본문에 있는 키는 허용되지 않습니다.

Authorization: Bearer rgn_live_...

키는 환경 변수 또는 비밀 정보 관리 서비스에 저장하세요. 브라우저 코드, 모바일 앱 패키지, 공개 저장소 및 로그에 넣지 마세요. 다른 출처의 브라우저 접근은 활성화되어 있지 않으므로 서버를 통해 요청하세요.

비활성화되거나 삭제되거나 만료된 키는 즉시 인증에 사용할 수 없게 됩니다. Regunow는 비밀 키의 해시만 저장하므로 기존 비밀 키를 다시 표시할 수 없습니다. 필요하면 대체 키를 만드세요.

Pro 이용 권한과 정책 동의는 요청마다 확인됩니다. legal_acceptance_required를 받으면 키 소유자가 로그인하여 법적 조건 동의를 열어야 합니다. API 키로는 정책에 동의할 수 없습니다.

GET/api/v1/models

지원 모델, 사고 수준, 관할권, 응답 언어 및 기능을 확인하세요. 이 인증 필수 엔드포인트에는 별도 크레딧 요금이 없으며 응답 생성 요청 전에 키를 확인하는 데 유용합니다.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

배포 환경의 모델 목록이 반환하는 값을 사용하세요. 관할권 모드에서는 model와 effort를 생략하면 허용된 기본값을 사용합니다. 지정한다면 기본 선택인 Sonnet 4.6 / 높음이어야 합니다. 첨부 파일이 없는 응답에서는 검색 서비스가 응답 모델을 관리하며, 응답의 모델 필드는 검증된 선택을 나타냅니다.

POST/api/v1/chat/completions

messages 배열을 포함한 JSON 본문을 보내세요. 기본적으로 API는 전체 답변을 JSON으로 반환합니다. 텍스트를 점진적으로 받으려면 stream를 true로 설정하세요.

{
  "messages": [{
    "role": "user",
    "content": "What retention period does this policy specify? Cite the document."
  }],
  "mode": "freestyle",
  "web_search": "off",
  "response_language": "en",
  "file_ids": ["YOUR_FILE_ID"]
}

YOUR_FILE_ID를 업로드 성공 시 반환된 UUID로 바꾸세요. 후속 질문마다 관련 사용자 및 어시스턴트 기록을 보내고 포함할 file_ids도 다시 보내세요. API는 대화 기록이나 첨부 파일을 자동으로 기억하지 않습니다.

시스템 메시지와 알 수 없는 필드는 거부됩니다. 이 API는 이미지 생성, 보고서 생성, 오디오 입력 또는 저장된 메모리 접근을 제공하지 않습니다. 업로드한 이미지를 질문 입력으로 사용할 수 있습니다.

응답 생성에 성공하면 object: "regunow.chat.completion", 답변, 출처 메타데이터, 사용량 및 시간이 반환됩니다. 다음 값은 예시입니다.

{
  "id": "request-uuid",
  "request_id": "request-uuid",
  "object": "regunow.chat.completion",
  "created": 1790812800,
  "model": "jp.anthropic.claude-sonnet-4-6",
  "latency": {
    "time_to_first_token_ms": 2345,
    "time_to_answer_completion_ms": 9876
  },
  "output": {
    "input_files": [],
    "role": "assistant",
    "content": "The complete answer...",
    "finish_reason": "end_turn",
    "citations": [],
    "sources": [],
    "web_search": false
  },
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 456,
    "charged_microcredits": 789000,
    "charged_credits": 0.789
  }
}

• output.content에는 최종 답변 텍스트가 있습니다. 인용 위치는 이 최종 문자열을 기준으로 하며 sourceIndexes는 output.sources의 항목을 나타냅니다.
• 출처에는 제목, 파일 이름, MIME 유형, URI 및 검색된 발췌문이 포함됩니다. 발췌문과 인용을 답변과 함께 표시하세요.
• 출처 URI는 위치를 나타내며 비공개 저장소를 가리킬 수 있습니다. 사용자가 열 수 있는 링크에는 공개 발행자 URL만 사용하세요. API는 규제 출처 파일의 다운로드나 번역을 제공하지 않습니다.
• 첨부 파일을 사용하면 output.input_files가 제공된 파일을 나타냅니다. 첨부 출처에는 file_id가 있고 규제 및 웹 출처에는 file_id: null가 있습니다. 첨부 파일 URI는 null입니다.
• 입력 파일이 있다고 해서 모든 주장을 뒷받침하는 것은 아닙니다. 모델이 본문 인용을 생략할 수 있고 이미지나 스캔의 발췌문은 비어 있을 수 있습니다.

검색 서비스가 토큰 수를 제공하지 않으면 null일 수 있습니다. 이는 알 수 없음을 뜻하며 0이 아닙니다. charged_credits는 기록된 고객 청구액입니다. created는 초 단위 Unix 타임스탬프이고 지연 시간은 밀리초 단위입니다.

모든 엔드포인트 응답에는 X-Request-Id 헤더가 있습니다. 문제 진단을 위해 이 식별자를 보관하세요. 채팅 응답과 오류 JSON에도 request_id가 포함됩니다.

"stream": true를 설정하세요. 응답은 text/event-stream를 사용합니다. cURL에서는 -N를 추가하여 출력 버퍼링을 끄세요.

curl --fail-with-body -N \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: streaming-question-001" \
  -d '{
    "messages": [{"role":"user","content":"Summarize EU product-safety obligations."}],
    "mode": "jurisdiction",
    "jurisdiction": "eu",
    "stream": true
  }'

빈 줄로 구분된 완전한 SSE 이벤트를 읽으세요. 네트워크 청크에는 이벤트의 일부 또는 여러 이벤트가 들어갈 수 있습니다. 도착하는 choices[0].delta.content를 이어 붙이세요. :로 시작하는 연결 유지 주석은 무시하세요.

data: {"choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{"content":"The answer begins..."},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"choices":[],"usage":{"prompt_tokens":1234,"completion_tokens":456,"total_tokens":1690},"regunow":{"output":{},"latency":{},"usage":{"charged_credits":0.789,"charged_microcredits":789000}}}

data: [DONE]

마지막 메타데이터 이벤트에는 빈 choices 배열이 있습니다. 최종 답변, 인용 및 출처는 regunow.output, 시간은 regunow.latency, 크레딧은 regunow.usage에서 읽으세요. 토큰 수는 usage.prompt_tokens와 usage.completion_tokens를 사용합니다.

검색과 인용 처리로 일시적인 중단이 생길 수 있습니다. 최종 메타데이터가 도착할 때까지 텍스트는 임시로 취급하세요. 스트리밍 시작 후 오류는 error 객체와 이어지는 [DONE]로 전달됩니다. HTTP 200만으로 성공이 확인되지는 않습니다. 그 이전의 인증 또는 검증 실패는 일반 JSON 오류 응답을 반환합니다.

완료된 작업의 재조회도 SSE이며, 저장된 답변을 하나의 텍스트 청크와 X-Idempotent-Replayed: true로 반환합니다.

문서나 이미지를 업로드한 뒤 해당 ID를 채팅 요청에 첨부하세요. 파일은 키 소유자의 라이브러리와 저장 용량을 공유합니다. 문서는 최대 10 MiB, 이미지는 최대 5 MiB입니다.

직접 업로드(권장)

이 3단계 절차는 원본 바이트를 저장소로 직접 보내 애플리케이션 요청 본문 제한을 피합니다. 호스팅된 통합에서, 특히 큰 파일에 사용하세요.

POST/api/v1/files/upload-intents

name, mime_type, bytes(정확한 파일 크기)만 보내세요. 성공하면 HTTP 201, 대기 중인 파일 ID, 300초간 유효한 서명된 업로드 URL이 반환됩니다.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/upload-intents" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-intent-001" \
  -d '{"name":"policy.txt","mime_type":"text/plain","bytes":16384}'

{
  "id": "YOUR_FILE_ID",
  "status": "pending",
  "upload_method": "PUT",
  "upload_url": "SIGNED_UPLOAD_URL",
  "upload_headers": {"Content-Type": "text/plain"},
  "expires_in": 300
}

FILE_ID를 반환된 id로 설정하세요. 반환된 upload_method, upload_url, upload_headers를 사용하여 정확한 원본 바이트를 업로드하세요. 정확한 Content-Length를 지정하세요. 업로드 URL에 Regunow API 키를 보내거나 서명된 URL을 로그에 기록하지 마세요.

# Set UPLOAD_URL from the intent response. Use its returned upload_headers.
# This example assumes policy.txt is exactly 16,384 bytes.
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: text/plain" \
  -H "Content-Length: 16384" \
  --data-binary @./policy.txt

POST/api/v1/files/{fileId}/complete

다른 멱등성 키로 {}를 보내세요. 완료 처리는 바이트를 검증하고 HTTP 200과 사용 가능한 파일을 반환합니다. 완료에 성공한 후에만 ID를 file_ids에 사용할 수 있습니다.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/$FILE_ID/complete" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-complete-001" \
  -d '{}'

URL이 만료되면 사용하지 않은 대기 파일을 삭제하고 새 키로 다시 준비하세요. 준비 응답을 재조회해도 URL 유효 기간은 연장되지 않습니다. 완료 결과가 불확실하면 먼저 파일 상태를 조회하세요. 여전히 대기 중이면 새 멱등성 키로 완료를 재시도하세요. 이전 키는 저장된 결과를 반환합니다. 이미 사용 가능한 파일을 완료하면 메타데이터를 반환합니다.

멀티파트 업로드

POST/api/v1/files

작은 파일은 file라는 이름의 multipart/form-data 필드 하나로 보내세요. base64나 원격 URL이 아닌 원본 바이트를 보내세요. 호스팅 게이트웨이는 API 파일 허용량보다 작은 본문 제한을 적용할 수 있습니다.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Idempotency-Key: policy-upload-001" \
  -F "file=@./policy.pdf;type=application/pdf"

업로드에 성공하면 HTTP 201과 사용 가능한 파일이 반환되며 별도 완료 호출은 필요하지 않습니다.

{
  "id": "YOUR_FILE_ID",
  "object": "regunow.file",
  "name": "policy.pdf",
  "mime_type": "application/pdf",
  "category": "file",
  "bytes": 16384,
  "status": "available",
  "created_at": "2026-10-01T00:00:00Z",
  "request_id": "request-uuid",
  "usage": {"charged_microcredits":500,"charged_credits":0.0005}
}

파일 목록, 조회 및 삭제

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files?limit=20" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

같은 계정의 키는 해당 라이브러리의 사용 가능한 파일에 접근할 수 있습니다. 없는 파일과 다른 계정의 파일은 모두 404를 반환합니다. 한 계정으로 여러 사용자에게 서비스를 제공한다면 파일을 첨부하거나 삭제하기 전에 자체 사용자 권한을 적용하세요.

대기 중이거나 실패한 업로드는 정리가 성공할 때까지 용량을 차지합니다. 24시간이 지난 미완료 업로드는 정리 대상입니다. 사용 가능한 파일은 업로드 검증을 통과했지만 추출은 질문 시 이루어지므로 손상되거나 암호화되거나 읽을 수 없는 문서는 분석 중 실패할 수 있습니다.

응답 생성, 업로드 및 삭제는 사용량을 기록합니다. 모델 목록 조회와 파일 메타데이터 읽기에는 별도 크레딧 요금이 없습니다. 문서 추출과 이미지 분석은 채팅 요청에서 청구됩니다.

usage.charged_credits에서 작업 요금을 확인하세요. 1크레딧은 1,000,000마이크로크레딧입니다. 키 크레딧 제한은 계정 크레딧과 별개이며 둘 다 요청을 막을 수 있습니다. 설정 → API 키에서 사용량을 확인하고 제한을 설정하세요.

각 메시지와 첨부 파일이 API 제한 이내여도 모델 컨텍스트 및 시각 입력 제한은 적용됩니다. 키 예산은 키 생성 시점이나 이전 기간 갱신 시점을 기준으로 일간, 주간 또는 월간의 순환 기간마다 초기화됩니다.

사용 가능한 예산으로 시작한 요청도 생성 후에 최종 비용이 결정되므로 적은 잔액을 약간 초과할 수 있습니다. 한도에 도달하면 새 응답 생성과 파일 변경이 중단됩니다. 예약은 동시 요청이 같은 키 예산을 중복 사용하지 않도록 합니다.

응답 생성, 업로드, 업로드 완료 및 삭제마다 Idempotency-Key를 보내세요. 선택 사항이지만 연결 실패 후 중복 작업과 청구를 막기 위해 강력히 권장합니다.

Idempotency-Key: a-unique-key-for-this-operation

• 새 작업마다 고유한 키를 만들고 원본 요청과 함께 저장하세요.
• 동일한 API 키, 멱등성 키 및 변경 없는 입력으로 재시도하세요. 정산 후 24시간 동안 저장된 상태와 응답을 추가 제공업체 호출이나 요금 없이 재조회할 수 있습니다.
• 재조회에는 X-Idempotent-Replayed: true가 포함됩니다. 입력을 바꾸거나 첫 요청이 진행 중일 때 같은 키를 사용하면 409를 반환합니다.
• 캐시된 결과에는 오류도 포함될 수 있습니다. 같은 키는 다시 실행하지 않고 같은 실패를 반환할 수 있습니다. 새 작업 전에 결과를 확인하세요.
• 재조회 기간이 만료된 후 같은 키를 사용하면 새 요청이 시작되어 추가 요금이 발생할 수 있습니다.

일시적인 네트워크, 요청 빈도 제한 또는 서비스 오류에는 지수 백오프를 사용하세요. 결과가 불확실한 요청을 해결하는 동안 같은 멱등성 키를 유지하세요. 잘못된 입력, 만료된 인증 정보 또는 크레딧 부족은 원인을 해결한 뒤 재시도하세요.

파일을 삭제해도 재조회 기간 내에 캐시된 응답 생성이나 업로드 응답은 지워지지 않습니다. 삭제 후 업로드 응답을 재조회하면 원본 응답을 반환하며 파일을 다시 만들지 않습니다.

오류는 일정한 JSON 구조를 사용합니다. 처리할 때 error.code를 확인하고 지원 문의 시 request_id 또는 X-Request-Id 헤더를 보관하세요.

{
  "error": {
    "type": "request_error",
    "code": "invalid_request",
    "message": "messages must contain 1 to 20 alternating user/assistant messages, end with a user message, and stay within 64,000 characters."
  },
  "request_id": "request-uuid"
}