# Linktary — the notary for links

Linktary is an enterprise certified safe-link URL shortener on linktary.com.
Every destination is verified to origin at link creation; every link carries
a public, machine-readable trust report. Corporate networks can allowlist
the single domain linktary.com.

## Verifying a link (for agents)

- HTML trust report:  https://linktary.com/v/<code>
- JSON trust report:  https://linktary.com/v/<code>.json
  (equivalently: GET /v/<code> with Accept: application/json)
- Service descriptor: https://linktary.com/.well-known/linktary.json

Verdicts: safe (direct 302) / caution (interstitial with destination preview;
POST /<code> with confirmed=yes to proceed) / blocked (refused, no bypass).

## API summary

- POST /api/auth/request-link {email} -> one-time magic-link sign-in (no passwords)
- POST /api/links {url} -> {code, short_url, trust_url, verdict} (auth required)
- GET  /api/links -> own links: code/verdict/clicks/created_at (never destinations)
- GET  /api/links/<code> -> detail incl. destination (owner only)
- POST /api/links/<code>/recheck -> re-run verification (owner only)
- DELETE /api/links/<code> -> soft delete (owner only)
- POST /api/report-abuse {code, reason} -> report a suspicious link (public, rate-limited)
- POST /api/waitlist {email, note?} -> join the Phase-2 enterprise waitlist (public, rate-limited, idempotent)

Rate limits: 5 sign-in emails/hour per address (+20/hour per IP),
60 link creates/hour per user, 600 redirects/minute per IP,
10 abuse reports/hour per IP, 10 waitlist signups/hour per IP.
Excess -> 429 with Retry-After.

## Blog + trust pages

- Blog index:        https://linktary.com/blog
- Articles:          https://linktary.com/blog/<slug>  (slugs: how-verification-works,
                     why-corporate-networks-block-shorteners,
                     the-honest-crypto-design, enterprise-buyers-guide,
                     anatomy-of-a-malicious-redirect-chain)
- Security:          https://linktary.com/security  (data flow, retention,
                     subprocessors, threat model, disclosure contact)
- Privacy:           https://linktary.com/privacy   (minimum-knowledge, plain language)
- Allowlist kit:     https://linktary.com/allowlist (the one domain to allow,
                     why it's safe, copy-paste ticket justification)
- Security contact:  https://linktary.com/security.txt (RFC 9116)

Contact: hello@linktary.com · Abuse: https://linktary.com/report-abuse

## Trust-report JSON schema

{
  "type": "object",
  "required": [
    "code",
    "verdict",
    "score",
    "signals",
    "chain",
    "checked_at",
    "verifier"
  ],
  "properties": {
    "code": {
      "type": "string",
      "description": "Short-link code (the path segment after /v/)."
    },
    "verdict": {
      "type": "string",
      "enum": [
        "safe",
        "caution",
        "blocked",
        "pending"
      ],
      "description": "Lowercase verification verdict."
    },
    "score": {
      "type": "number",
      "description": "Additive engine score: the sum of the stored signal weights. >= 100 is blocked, >= 40 is caution."
    },
    "signals": {
      "type": "array",
      "description": "Every recorded signal, including informational ones.",
      "items": {
        "type": "object",
        "required": [
          "code",
          "severity",
          "weight",
          "plain_text"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "warn",
              "block"
            ]
          },
          "weight": {
            "type": "number"
          },
          "plain_text": {
            "type": "string",
            "description": "Human-readable explanation of the signal."
          }
        }
      }
    },
    "chain": {
      "type": "array",
      "description": "Redirect hops followed at verification time, in order.",
      "items": {
        "type": "object",
        "required": [
          "url",
          "status",
          "content_type",
          "content_length",
          "https",
          "final"
        ],
        "properties": {
          "url": {
            "type": "string"
          },
          "status": {
            "type": "number"
          },
          "content_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "content_length": {
            "type": [
              "number",
              "null"
            ]
          },
          "https": {
            "type": "boolean"
          },
          "final": {
            "type": "boolean",
            "description": "True for the last hop — the destination."
          }
        }
      }
    },
    "checked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "ISO-8601 timestamp of the verification; null if never checked."
    },
    "verifier": {
      "type": "string",
      "description": "Brand that performed the verification (env BRAND_NAME)."
    }
  }
}