API

API

Markedfile API로 파일에 표시를 넣고 확인해요. Business와 Enterprise 요금제에서 쓸 수 있어요.

API 키

Business 또는 Enterprise 작업 공간의 소유자가 공간 설정에서 키를 만들고 폐기해요. 키는 한 번만 보여 줘요. Markedfile은 SHA-256 해시, 짧은 접두사, 이름을 저장해요. 비밀은 저장하지 않아요.

키는 정확히 하나의 공간에 속해요. 그 공간에서만, 그 공간 요금제의 한도로 동작해요. 개인 공간에는 키가 없어요. 소유자가 아닌 구성원은 키를 만들거나 폐기할 수 없어요.

공간이 활성 Business 또는 Enterprise 요금제를 잃으면 모든 키가 바로 동작을 멈춰요. 기존 파일을 앱에서 아직 30일 동안 탐지할 수 있는 동안에도 그래요. Business 또는 Enterprise로 돌아오면, 폐기하지 않은 키는 다시 동작해요.

인증

Authorization 헤더에 비밀을 Bearer 토큰으로 보내요. 이 경로는 세션 쿠키를 쓰지 않아요. 다른 페이지의 브라우저는 거절해요.

감사

만들기, 폐기, 표시, 탐지는 공간 소유자가 읽을 수 있는 감사 행을 적어요. 그 행에는 파일이 들어 있지 않아요.

엔드포인트

POST/api/v1/mark

파일에 표시를 넣고 표시된 사본을 돌려줘요. 본문은 multipart/form-data예요.

인증

Authorization: Bearer mf_…

이 헤더 줄을 보내요. 세션 쿠키는 없어요. curl과 다른 서버 클라이언트는 받아요. 다른 페이지의 브라우저는 거절해요.

매개변수

이름유형필수설명
filefile예표시할 파일이에요. Business와 Enterprise는 최대 100MB, PDF 500쪽, 영상 10분까지 받아요. 업로드 크기, 영상 길이, PDF 쪽수는 공간의 요금제를 따라요.
identifierstring예1–32자이고, 제어 문자는 없어요. 이 사본이 나중에 확인될 때 보이는 라벨이에요. 읽을 수 있는 텍스트로 파일에 쓰이지 않아요.

요청

curl -X POST https://markedfile.com/api/v1/mark \
  -H "Authorization: Bearer mf_…" \
  -F "file=@contract.pdf" \
  -F "identifier=northwind"

응답

{
  "file": "JVBERi0xLjQK…",
  "mime": "application/pdf",
  "name": "contract.pdf",
  "kind": "pdf",
  "layers": [
    {
      "name": "Metadata",
      "detail": "Authenticated workspace reference; the identifier stays on the server",
      "screenshot": "No",
      "crop": "No",
      "reencode": "No"
    }
  ],
  "remaining": 1
}

file은 base64로 된 표시된 바이트예요. mime, name, kind는 다운로드를 설명해요. layers는 쓰인 층을 보여 줘요. 요금제에 활성 파일 한도가 없으면 remaining은 이번 표시 뒤의 활성 파일 수예요. 한도가 있으면 remaining은 남은 새 표시 수예요. Business와 Enterprise에는 활성 파일 한도가 없어요. 파일을 삭제하면 탐지가 끝나요.

오류

JSON 응답의 error 필드 텍스트는 영어예요.

상태설명
400파일이 비어 있거나, 식별자가 비어 있거나, 32자를 넘거나, 제어 문자가 있어요.
401키가 없거나, 폐기됐거나, 알 수 없어요. JSON 응답에 "code": "api-key"가 있어요.
403작업 공간에 활성 Business 또는 Enterprise 요금제가 없어요(응답에 "code": "enterprise"가 있어요). 또는 브라우저가 cross-site나 same-site 요청을 보냈어요.
413파일이 요금제의 업로드 한도를 넘거나, PDF 쪽수가 요금제 한도보다 많아요.
422파일을 처리하지 못했어요.
429이 키가 현재 1분 안에 40개보다 많은 파일에 표시를 넣었어요.

호출 한도

이 키는 분당 40회예요. 카운터는 제품 데이터베이스에 있고 재시작 뒤에도 남아요.

POST/api/v1/detect

이 키의 작업 공간에서 파일을 확인해요. 본문은 multipart/form-data예요.

인증

Authorization: Bearer mf_…

이 헤더 줄을 보내요. 세션 쿠키는 없어요. curl과 다른 서버 클라이언트는 받아요. 다른 페이지의 브라우저는 거절해요.

매개변수

이름유형필수설명
filefile예확인할 파일이에요. 일치는 이 키의 공간에서만 찾아요. 다른 공간에서 표시한 파일은 알아보지 못해요. 활성 Business 또는 Enterprise 공간은 영상 파일도 확인할 수 있어요. 한 프레임의 화면 캡처는 이미지로 확인해요.

요청

curl -X POST https://markedfile.com/api/v1/detect \
  -H "Authorization: Bearer mf_…" \
  -F "file=@leaked.pdf"

응답

{
  "id": "northwind",
  "confidence": 0.95,
  "layers": [
    {
      "name": "Metadata",
      "hit": true,
      "detail": "Authenticated metadata matched this workspace",
      "screenshot": "No",
      "crop": "No",
      "reencode": "No"
    }
  ],
  "notes": [
    "Confidence is 99% for an exact file or when an authenticated mark agrees with another mark. A visual match alone stays lower, and weak bit agreement stays far from a high score."
  ]
}

id는 사본에 표시를 넣을 때 정한 식별자예요. 이 공간에 일치가 없으면 null이에요. confidence는 파일이 정확히 같을 때, 또는 검증된 표시가 다른 표시와 맞을 때 99%예요. 시각적 일치만 있으면 더 낮게 남아요. layers는 층을 보여 주고, 맞는 층의 hit은 true예요. notes는 확인이 한 일을 설명해요. 삭제한 파일은 알아보지 못해요.

오류

JSON 응답의 error 필드 텍스트는 영어예요.

상태설명
400파일이 비어 있어요.
401키가 없거나, 폐기됐거나, 알 수 없어요. JSON 응답에 "code": "api-key"가 있어요.
403작업 공간에 활성 Business 또는 Enterprise 요금제가 없어요(응답에 "code": "enterprise"가 있어요). 또는 브라우저가 cross-site나 same-site 요청을 보냈어요.
413파일이 요금제의 업로드 한도를 넘거나, PDF 쪽수가 요금제 한도보다 많아요.
422파일을 처리하지 못했어요.
429이 키가 현재 1분 안에 80회보다 많은 탐지를 했어요.

호출 한도

이 키는 분당 80회예요. 카운터는 제품 데이터베이스에 있고 재시작 뒤에도 남아요.