generated: '2026-08-11'
method: derived
source: openapi/imgauth-api-di-attestazione-opere-digitali-openapi-original.json
docs: https://attestazione.spaziogenesi.org/en/developer/
note: >-
  Cross-cutting semantics for an API that is deliberately small, stateless and un-RESTful in shape: there
  are no collections, no resources to page through and no resource identifiers other than the SHA-256
  fingerprint itself. Several conventions a general-purpose API would carry are therefore genuinely
  absent rather than undocumented, and are recorded as false below.
language:
  contract_language: it
  note: >-
    Field names are Italian BY DESIGN and the contract says so explicitly — attestazione, hmac, titolo,
    autore, anno, note, fascia, timestamp_iso, dimensione_bytes, tipo_mime. Do not translate them. Some
    response fields (status, token, count, items, components) are English. A client must handle a mixed
    vocabulary; an agent reading only English field names will miss the primary payload.
authentication:
  style: optional-credential
  schemes:
    - {name: agentBearer, type: http bearer, format: 'sg_k_<id>_<secret> or sg_s_<id>_<secret>'}
    - {name: voucherHeader, type: apiKey header, parameter: X-SG-Voucher, ttl: 8h}
  note: >-
    Unusual and worth stating plainly: authentication is OPTIONAL on every operation. A credential does
    not unlock data — it only bypasses the Turnstile anti-bot challenge on POST /api/hash and
    POST /api/cert-pdf and applies the tier quota. HMAC verification, the server timestamp and the per-IP
    rate limits are identical with or without it. Everything else in the API is fully anonymous.
  see: authentication/imgauth-api-di-attestazione-opere-digitali-authentication.yml
idempotency:
  supported: false
  header: null
  note: >-
    No Idempotency-Key header, parameter or documented semantic anywhere in the contract. Re-posting the
    same fingerprint to POST /api/hash issues a NEW attestation with a new timestamp rather than returning
    the first — the archive explicitly keeps multiple issuances and GET /api/cert resolves the OLDEST.
    A retried attestation after a network timeout is therefore a duplicate, not a no-op. Genuinely absent.
pagination:
  supported: false
  note: >-
    No paged collection exists. GET /api/integrations returns the full approved list with a count, and
    GET /api/status-history returns a fixed 90-day window. No cursor, offset, limit or page parameter.
filtering:
  supported: partial
  note: 'GET /api/health-log takes an optional `day` parameter; GET /c/{hash} and /agent/authorize take `lang`.'
field_expansion:
  supported: false
metadata:
  supported: true
  fields: [titolo, autore, anno, note]
  note: >-
    Declared metadata is normalised and BOUND INTO the HMAC signature, so it is immutable after issuance —
    but it stays self-declared and proves nothing about authorship. To verify a certificate that carried
    metadata, the caller must resupply all four fields EXACTLY as printed or the signature will not match.
request_tracing:
  request_id_header: null
  supported: false
  note: no correlation or request-id header is returned; a caller cannot cite a request when reporting a fault
versioning:
  scheme: none-in-transport
  current: 1.34.1
  note: >-
    One unversioned live contract. The version appears in OpenAPI info.version and in GET /ping, not in the
    path and not in a header. No Accept-version negotiation. See lifecycle/.
  see: lifecycle/imgauth-api-di-attestazione-opere-digitali-lifecycle.yml
error_envelope:
  media_type: application/json
  shape: '{"error": "<string>"}'
  schema: components.schemas.Errore
  rfc9457: false
  note: single free-text field; no machine-readable code to branch on below the HTTP status
  see: errors/imgauth-api-di-attestazione-opere-digitali-problem-types.yml
rate_limit_signaling:
  response_headers: []
  retry_after: false
  status_on_exhaustion: 429
  note: >-
    limits are documented per operation but not signalled at runtime — no RateLimit-*, X-RateLimit-* or
    Retry-After header was observed on a live 200
  see: rate-limits/imgauth-api-di-attestazione-opere-digitali-rate-limits.yml
caching:
  supported: true
  note: >-
    Deliberate and documented per endpoint: badges 24h when green / 60s when grey, status 180s with
    stale-while-revalidate, integrations 60s. CORS is open on the public telemetry endpoints.
transport:
  https_only: true
  hsts: 'max-age=31536000; includeSubDomains'
  cors: 'Access-Control-Allow-Origin: * on public read endpoints'
  content_type: application/json except multipart/form-data on POST /api/verify and binary on PDF/SVG/OTS responses
privacy_invariant:
  note: >-
    The defining convention of this API: file bytes never transit. The client computes the SHA-256 and
    sends only the 64-hex fingerprint. The MCP tool schemas repeat the rule verbatim and instruct agents
    never to pass file contents or base64 as tool arguments. The legacy inline-base64 path on
    POST /api/hash is the one exception and is capped at 100 MB.