API
API
Marca e rileva file con l'API di Markedfile. Disponibile sui piani Business e Enterprise.
Chiavi API
Il proprietario di uno spazio di lavoro Business o Enterprise crea e revoca le chiavi nelle impostazioni dello spazio. Una chiave viene mostrata una sola volta. Markedfile memorizza un hash SHA-256, un prefisso breve e il nome. Non memorizza il segreto.
Una chiave appartiene a un solo spazio di lavoro. Agisce solo lì, con i limiti del piano di quello spazio. Gli spazi personali non hanno chiavi. Un membro che non è il proprietario non può crearle né revocarle.
Se lo spazio di lavoro perde il piano Business o Enterprise attivo, tutte le chiavi smettono di funzionare subito, anche durante i 30 giorni in cui i file esistenti si possono ancora rilevare nell'applicazione. Tornando a Business o a Enterprise, le chiavi che non sono state revocate tornano a funzionare.
Autenticazione
Invia il segreto nell'intestazione Authorization come token Bearer. Questi endpoint non usano un cookie di sessione. Un browser su un altro sito viene rifiutato.
Audit
Creare, revocare, marcare e rilevare scrivono una riga di audit che il proprietario dello spazio di lavoro può leggere. La riga non include il file.
Endpoint
POST/api/v1/mark
Marca un file e restituisce la copia marcata. Il corpo è multipart/form-data.
Autenticazione
Authorization: Bearer mf_…Invia questa intestazione. Non c'è un cookie di sessione. curl e gli altri client da server sono accettati. Un browser su un altro sito viene rifiutato.
Parametri
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| file | file | Sì | Il file da marcare. Business e Enterprise accettano fino a 100 MB, 500 pagine di PDF e video fino a 10 minuti. La dimensione del caricamento, la durata del video e il numero di pagine del PDF seguono il piano dello spazio di lavoro. |
| identifier | string | Sì | Da 1 a 32 caratteri, senza caratteri di controllo. È l'etichetta che vedi se quella copia viene rilevata dopo. Non viene scritta nel file come testo leggibile. |
Richiesta
curl -X POST https://markedfile.com/api/v1/mark \
-H "Authorization: Bearer mf_…" \
-F "file=@contract.pdf" \
-F "identifier=northwind"Risposta
{
"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 sono i byte marcati in base64. mime, name e kind descrivono il download. layers elenca i livelli che sono stati applicati. Quando il piano non ha un limite di file attivi, remaining è il numero di file attivi dopo questa marca. Quando ha un limite, remaining è quante marche nuove restano. Business e Enterprise non hanno un limite di file attivi. È l'eliminazione di un file che termina il rilevamento.
Errori
Il testo del campo error nel corpo JSON è in inglese.
| Stato | Descrizione |
|---|---|
| 400 | Il file è vuoto, oppure l'identificatore è vuoto, ha più di 32 caratteri o contiene un carattere di controllo. |
| 401 | La chiave manca, è stata revocata o è sconosciuta. Il corpo JSON include "code": "api-key". |
| 403 | Lo spazio di lavoro non ha più un piano Business o Enterprise attivo (il corpo include "code": "enterprise"), oppure il browser ha inviato una richiesta cross-site o same-site. |
| 413 | Il file supera il limite di caricamento del piano, oppure il PDF ha più pagine di quante il piano consenta. |
| 422 | Non è stato possibile elaborare il file. |
| 429 | Questa chiave ha marcato più di 40 file nel minuto attuale. |
Limite di richieste
40 richieste al minuto per questa chiave. Il contatore sta nel database del prodotto e resta valido dopo un riavvio.
POST/api/v1/detect
Verifica un file nello spazio di lavoro di questa chiave. Il corpo è multipart/form-data.
Autenticazione
Authorization: Bearer mf_…Invia questa intestazione. Non c'è un cookie di sessione. curl e gli altri client da server sono accettati. Un browser su un altro sito viene rifiutato.
Parametri
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| file | file | Sì | Il file da verificare. La corrispondenza viene cercata solo nello spazio di lavoro di questa chiave. Un file marcato in un altro spazio di lavoro non viene identificato. Uno spazio Business o Enterprise attivo può anche verificare un file video. Lo screenshot di un singolo fotogramma viene verificato come immagine. |
Richiesta
curl -X POST https://markedfile.com/api/v1/detect \
-H "Authorization: Bearer mf_…" \
-F "file=@leaked.pdf"Risposta
{
"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 è l'identificatore che hai definito quando quella copia è stata marcata, o null quando questo spazio di lavoro non ha una corrispondenza. confidence è del 99% per un file esatto o quando una marca autenticata concorda con un'altra marca. Una corrispondenza solo visiva resta più bassa. layers elenca i livelli, e hit è true in quelli che hanno concordato. notes descrive cosa ha fatto la verifica. Un file eliminato non viene identificato.
Errori
Il testo del campo error nel corpo JSON è in inglese.
| Stato | Descrizione |
|---|---|
| 400 | Il file è vuoto. |
| 401 | La chiave manca, è stata revocata o è sconosciuta. Il corpo JSON include "code": "api-key". |
| 403 | Lo spazio di lavoro non ha più un piano Business o Enterprise attivo (il corpo include "code": "enterprise"), oppure il browser ha inviato una richiesta cross-site o same-site. |
| 413 | Il file supera il limite di caricamento del piano, oppure il PDF ha più pagine di quante il piano consenta. |
| 422 | Non è stato possibile elaborare il file. |
| 429 | Questa chiave ha fatto più di 80 rilevamenti nel minuto attuale. |
Limite di richieste
80 richieste al minuto per questa chiave. Il contatore sta nel database del prodotto e resta valido dopo un riavvio.