API
API
Mark and detect files with the Markedfile API. Available only on the Enterprise plan.
API keys
The owner of an Enterprise workspace creates and revokes keys in workspace settings. A key is shown once. Markedfile stores a SHA-256 hash, a short prefix, and the name. It does not store the secret.
A key belongs to exactly one workspace. It acts only there, with that workspace's plan limits. Personal workspaces do not have keys. A member who is not the owner cannot create or revoke them.
If the workspace loses its active Enterprise plan, every key stops working immediately, including during the 30 days that existing files can still be detected in the app. Coming back to Enterprise makes the keys that were not revoked work again.
Authentication
Send the secret in the Authorization header as a Bearer token. These routes do not use a session cookie. A browser on another site is rejected.
Audit
Creating, revoking, marking, and detecting write an audit row the workspace owner can read. The row does not include the file.
Endpoints
POST/api/v1/mark
Marks a file and returns the marked copy. The body is multipart/form-data.
Authentication
Authorization: Bearer mf_…Send this header. There is no session cookie. curl and other server clients are accepted. A browser on another site is rejected.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| file | file | Yes | The file to mark. Enterprise accepts up to 100 MB and 500 PDF pages. Upload size and PDF page count follow the workspace plan. |
| identifier | string | Yes | 1–32 characters, with no control characters. The label you see if this copy is detected later. It is not written into the file as readable text. |
Request
curl -X POST https://markedfile.com/api/v1/mark \
-H "Authorization: Bearer mf_…" \
-F "file=@contract.pdf" \
-F "identifier=northwind"Response
{
"file": "JVBERi0xLjQK…",
"mime": "application/pdf",
"name": "contract.pdf",
"kind": "pdf",
"layers": [
{
"name": "Opaque PDF fields",
"detail": "Three authenticated copies; no identifier text",
"screenshot": "No",
"crop": "No",
"reencode": "No"
}
],
"remaining": 1
}file is the marked bytes in base64. mime, name, and kind describe the download. layers lists the carriers that were applied. When the plan has no active-file cap, remaining is the number of active files after this mark. When it has a cap, remaining is how many new marks are left. Enterprise has no active-file cap. Deleting a file is what ends detection.
Errors
The error field in the JSON body is English.
| Status | Description |
|---|---|
| 400 | The file is empty, or the identifier is empty, longer than 32 characters, or contains a control character. |
| 401 | The key is missing, revoked, or unknown. The JSON body includes "code": "api-key". |
| 403 | The workspace no longer has an active Enterprise plan (the body includes "code": "enterprise"), or the browser sent a cross-site or same-site fetch. |
| 413 | The file is over the plan upload limit, or the PDF has more pages than the plan allows. |
| 422 | The file could not be processed. |
| 429 | This key has marked more than 40 files in the current minute. |
Rate limit
40 requests per minute for this key. The counter is stored in the product database and survives a restart.
POST/api/v1/detect
Checks a file against this key's workspace. The body is multipart/form-data.
Authentication
Authorization: Bearer mf_…Send this header. There is no session cookie. curl and other server clients are accepted. A browser on another site is rejected.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| file | file | Yes | The file to check. The match is looked up only in this key's workspace. A file marked in another workspace does not resolve. |
Request
curl -X POST https://markedfile.com/api/v1/detect \
-H "Authorization: Bearer mf_…" \
-F "file=@leaked.pdf"Response
{
"id": "northwind",
"confidence": 0.9,
"layers": [
{
"name": "Opaque PDF fields",
"hit": true,
"detail": "1 authenticated field(s) recovered",
"screenshot": "No",
"crop": "No",
"reencode": "No"
}
],
"notes": [
"Confidence is a heuristic for validated layer matches, not a measured forensic probability."
]
}id is the identifier you assigned when that copy was marked, or null when this workspace has no match. confidence is a heuristic for the validated layers, not a measured probability. layers lists the carriers, and hit is true on the ones that agreed. notes describes what the check did. A deleted file does not resolve.
Errors
The error field in the JSON body is English.
| Status | Description |
|---|---|
| 400 | The file is empty. |
| 401 | The key is missing, revoked, or unknown. The JSON body includes "code": "api-key". |
| 403 | The workspace no longer has an active Enterprise plan (the body includes "code": "enterprise"), or the browser sent a cross-site or same-site fetch. |
| 413 | The file is over the plan upload limit, or the PDF has more pages than the plan allows. |
| 422 | The file could not be processed. |
| 429 | This key has run more than 80 detections in the current minute. |
Rate limit
80 requests per minute for this key. The counter is stored in the product database and survives a restart.