riferimento api

API OSINTCORD v1

Un'API REST che espone esattamente gli stessi pivot del desk: inserisci un bersaglio, restituisce collegamenti a fonti pubbliche, organizzati per modulo. Risposte in JSON, autenticazione tramite chiave.

Introduzione

Tutte le richieste passano attraverso un URL di base con versione. Il corpo delle risposte è sempre in JSON codificato in UTF-8. Gli errori seguono un formato costante (vedi codici di errore).

https://api.osintcord.example/v1

Dominio di esempio — sostituisci osintcord.example con il tuo dominio una volta distribuita l'API. Il desk e l'API restituiscono gli stessi pivot.

Autenticazione

Ogni richiesta deve includere la tua chiave API nell'intestazione Authorization, nel formato Bearer <chiave>. La tua chiave è associata al tuo account con accesso completo.

mg_live_••••••••••••••••

# esempio di intestazione
Authorization: Bearer mg_live_la_tua_chiave_qui

Mantieni segreta la tua chiave. Non inserirlo in codice frontend pubblico o in un repository. Rigenerala in caso di leak (la vecchia verrà invalidata).

Quote e limiti

Tutti gli account ricevono l’entitlement massimo e non hanno una quota giornaliera di piano. Le risposte restituiscono lo stato corrente nelle campi quota.limit e quota.remaining (null indica illimitato). I limiti anti-abuso HTTP restano attivi.

account	richieste	funzionalità
Tutti gli account	illimitate a livello di piano	tutte quelle implementate

Restano attivi i limiti anti-abuso per proteggere il servizio.

Endpoint

GET/detect🔑 chiave richiesta

Rileva il tipo di un bersaglio (email, dominio, ip, username, wallet…) senza avviare una ricerca.

parametro	tipo	descrizione
value	string · obbligatorio	il bersaglio da analizzare

# richiesta
curl -H "Authorization: Bearer $OSINT_KEY" \
  "https://api.osintcord.example/v1/detect?value=crt.sh"

# risposta 200
{ "value": "crt.sh", "type": "domain" }

GET/osint/modules🔑 chiave richiesta

Elenca i moduli disponibili e i tipi di bersaglio supportati.

# risposta 200 — caricamento…

GET/osint/lookup🔑 chiave richiesta

Il cuore dell'API: restituisce l'elenco dei pivot (fonti pubbliche) per un bersaglio, organizzati per modulo. Consuma una richiesta dalla quota.

parametro	tipo	descrizione
value	string · obbligatorio	il bersaglio
type	string · default `auto`	forza un tipo (vedi tipi)
modules	string · opzionale	filtra, separati da virgola (es. `domain,net`)

# richiesta
curl -H "Authorization: Bearer $OSINT_KEY" \
  "https://api.osintcord.example/v1/osint/lookup?value=wikipedia.org&type=auto"

# risposta 200 — caricamento…

GET/osint/dorks🔑 chiave richiesta

Genera query Google avanzate («dorks») adatte al bersaglio.

# risposta 200
{
  "target": "esempio.it",
  "type": "domain",
  "dorks": [
    "site:esempio.it (login OR admin OR portale)",
    "site:esempio.it filetype:pdf",
    "site:*.esempio.it -site:www.esempio.it"
  ]
}

GET/account🔑 chiave richiesta

Restituisce il piano e lo stato della quota dell'account associato alla chiave.

# risposta 200
{
  "username": "megumin",
  "plan": "equipe",
  "quota": { "limit": null, "used": 142, "remaining": null, "unlimited": true }
}

Moduli

Ogni pivot restituito da /osint/lookup include un campo module.

chiave	modulo	cosa copre

Tipi di bersaglio

Valori accettati dal parametro type (o rilevati tramite auto).

tipo	etichetta	esempio

Codici di errore

codice	significato	causa
400	bad_request	parametro mancante o non valido
401	unauthorized	chiave assente o non valida
404	not_found	endpoint o tipo sconosciuto
429	rate_limited	limite anti-abuso di richieste superato

# formato di errore
{ "error": { "code": "rate_limited", "message": "Limite anti-abuso di richieste raggiunto." } }

Esempi

# bash
OSINT_KEY="mg_live_la_tua_chiave"
curl -H "Authorization: Bearer $OSINT_KEY" \
  "https://api.osintcord.example/v1/osint/lookup?value=1.1.1.1"

// Node / browser
const res = await fetch(
  "https://api.osintcord.example/v1/osint/lookup?value=1.1.1.1",
  { headers: { Authorization: `Bearer ${process.env.OSINT_KEY}` } }
);
const data = await res.json();
console.log(data.pivots);

# Python (requests)
import os, requests
r = requests.get(
    "https://api.osintcord.example/v1/osint/lookup",
    params={"value": "1.1.1.1"},
    headers={"Authorization": f"Bearer {os.environ['OSINT_KEY']}"},
)
print(r.json()["pivots"])