@extends('layouts.app')
@section('title', 'API')
@php $base = url('/api/v1'); @endphp
@section('content')
<div class="prose">
<h1>API</h1>
<p class="lede">Scan files, links and hashes from your own tools. Create a key on your <a href="{{ route('account') }}#api-keys">account page</a> and send it in the <code>x-apikey</code> header.</p>
<p>Limits: {{ config('vizur.api.per_minute') }} requests a minute and {{ number_format(config('vizur.api.per_day')) }} a day per key. Scans run in the background: submit, then fetch the analysis until <code>status</code> is <code>completed</code>.</p>

<div class="endpoint"><span class="method post">POST</span><code>/api/v1/files</code></div>
<p>Upload a file (multipart field <code>file</code>, up to {{ config('vizur.max_upload_mb') }} MB). Optional <code>force=1</code> to rescan, <code>private=1</code> to hide the report from others.</p>
<pre class="pre">curl -H "x-apikey: YOUR_KEY" -F "file=@invoice.pdf" {{ $base }}/files</pre>

<div class="endpoint"><span class="method post">POST</span><code>/api/v1/scan</code></div>
<p>Scan a URL, domain, IP address, or look up an MD5/SHA-1/SHA-256 hash. The type is detected for you.</p>
<pre class="pre">curl -H "x-apikey: YOUR_KEY" -d "query=https://example.com/login" {{ $base }}/scan</pre>

<div class="endpoint"><span class="method">GET</span><code>/api/v1/analyses/{id}</code></div>
<p>Status and, once finished, the full result for every engine plus details.</p>
<pre class="pre">curl -H "x-apikey: YOUR_KEY" {{ $base }}/analyses/01JB...</pre>
<pre class="pre">{
  "data": {
    "id": "01JB...", "type": "file", "status": "completed", "verdict": "malicious",
    "stats": { "malicious": 3, "suspicious": 0, "harmless": 0, "undetected": 4, ... },
    "file": { "name": "invoice.pdf.exe", "sha256": "...", ... },
    "results": { "ClamAV": { "category": "malicious", "result": "Win.Trojan.Agent-123" }, ... },
    "details": { ... }
  }
}</pre>

<div class="endpoint"><span class="method">GET</span><code>/api/v1/files/{hash}</code></div>
<p>Latest report for a file by MD5, SHA-1 or SHA-256. Returns 404 if nobody has scanned it here yet.</p>

<div class="endpoint"><span class="method">GET</span><code>/api/v1/search?query=…</code></div>
<p>Latest existing report for a URL, domain, IP or hash, without starting a new scan.</p>

<div class="endpoint"><span class="method">GET</span><code>/api/v1/engines</code> and <code>/api/v1/me</code></div>
<p>Active engines, and your key's usage against its limits.</p>

<h2 style="margin-top:36px">Verdicts and categories</h2>
<p><code>verdict</code> is <code>malicious</code>, <code>suspicious</code>, <code>clean</code> or <code>unknown</code>. Each engine result has a <code>category</code>: <code>malicious</code>, <code>suspicious</code>, <code>harmless</code>, <code>undetected</code>, <code>unsupported</code>, <code>timeout</code> or <code>failure</code>.</p>
<h2>Errors</h2>
<p>Errors return <code>{"error": {"code": "...", "message": "..."}}</code> with status 401 (bad key), 404, 422 (bad input) or 429 (limit reached; see <code>Retry-After</code>).</p>
</div>
@endsection