# datalink API for agents

datalink is a personal repository of links to data and resources. Each entry is a URL plus
a title, notes, a project and tags. The server checks every entry periodically to see whether
it still exists, and can keep compressed archived copies of entries that opt in.

## Auth

Send your token on every request:

    Authorization: Bearer <token>

(`X-API-Key: <token>` also works.) A `read` token can list and fetch. A `write` token can also
add, edit, delete, check and archive. 401 means the token is missing or wrong; 403 means it is
read-only.

## Adding what you find

    POST /api/entries
    Content-Type: application/json

    {
      "url": "https://example.com/some/data.csv",   // required, absolute http(s) URL
      "title": "Short human-readable name",
      "notes": "What it contains, why it is useful, how you found it, caveats.",
      "project": "AA_Trading",                      // which project it belongs to
      "tags": ["fx", "daily", "csv"],               // lowercase keywords
      "archive": true                                // keep a compressed copy on the server
    }

Adding is idempotent on the URL: if the URL already exists you get `200` with
`"created": false` and the existing entry, instead of a duplicate (new entries return `201`).
Use `PATCH` to improve an existing entry's notes or tags.

Add many at once (up to 500):

    POST /api/entries/bulk
    {"entries": [ {...}, {...} ]}

Guidelines:
- Search first (`GET /api/entries?q=...`) to see what is already stored.
- Prefer the most direct, stable URL (the data file or API endpoint, not a page that links to it).
- Write notes that let a human decide in five seconds whether the link matters.
- Set `"archive": true` for data that might disappear or change (files, reports, tables).
  Don't archive huge files or pages that change every minute.

## Reading

    GET /api/entries?q=&project=&tag=&status=&archive=&limit=100&offset=0
    GET /api/entries/{id}                 // includes its snapshots
    GET /api/projects                     // projects with counts
    GET /api/tags                         // tags with counts
    GET /api/stats
    GET /api/export                       // everything as JSON

`status` is one of: `ok`, `restricted` (exists but refused us: 401/403/429), `gone` (404/410),
`broken` (other errors), `unreachable` (DNS/timeout/connection), `unknown` (not checked yet).
`status=failing` matches gone, broken and unreachable together.

## Editing and maintenance

    PATCH  /api/entries/{id}              // any subset of url, title, notes, project, tags, archive
    DELETE /api/entries/{id}              // also deletes its archived copies
    POST   /api/entries/{id}/check        // check it now; returns the result
    POST   /api/entries/{id}/snapshot     // archive a copy now (works even if archive is off)

## Archived copies

    GET /api/entries/{id}/snapshots
    GET /api/snapshots/{snapshot_id}/content            // original bytes, decompressed
    GET /api/snapshots/{snapshot_id}/content?download=true
    GET /api/snapshots/{snapshot_id}/raw                // the stored .gz file

A new snapshot is stored only when the content changed since the last one; the newest few are kept.
For HTML pages only the HTML itself is saved, not images or scripts.

Full OpenAPI reference: `/docs` (interactive) and `/openapi.json`.