# onelink.ninja

> Shareable link lists. Anyone can publish a list of links at a short URL, with
> no account. Creating one returns a secret edit token; a list can later be
> claimed by an account, after which the token stops working.

## Reading a list

- https://onelink.ninja/l/{id}      HTML page for a list.
- https://onelink.ninja/l/{id}.md   The same list as plain Markdown. Prefer this one — it is
                        cheaper to read than the HTML and has no markup to strip.
                        Every HTML page advertises it via
                        <link rel="alternate" type="text/markdown">.
- https://onelink.ninja/random      302-redirects to a random list that has at least one link.

## Writing a list

A JSON REST API creates and edits lists without a browser. Writes require
Content-Type: application/json.

- POST   https://onelink.ninja/api/lists             Create. Body: {title, description?, links:[{url,label,description?}]}
                                         Returns {id, publicUrl, editUrl, editToken, markdownUrl}.
- GET    https://onelink.ninja/api/lists/{id}        Read.
- PATCH  https://onelink.ninja/api/lists/{id}        Update title/description/links.
- DELETE https://onelink.ninja/api/lists/{id}        Delete.
- POST   https://onelink.ninja/api/lists/{id}/links  Append one link: {url, label, description?}.
- GET    https://onelink.ninja/api/lists/random      Random list as JSON, no redirect to follow.

Write endpoints take `Authorization: Bearer {editToken}`, or a session cookie
that owns the list once it has been claimed.

Create a list in one call:

  curl -X POST https://onelink.ninja/api/lists \
    -H 'content-type: application/json' \
    -d '{"title":"My list","links":[{"url":"https://example.com","label":"Example"}]}'

The editToken returned at creation is the only credential for an unclaimed list.
Hand it back to the person you made the list for, and warn them it is the sole
way back into editing.

## Errors

Failures are {"error":{"code","message","details"?}}. Branch on code, not message:

  invalid_body (400) · missing_credentials (401) · invalid_credentials (403)
  not_found (404) · rate_limited (429)

## Notes

- No API key is needed to create a list. Creation is rate limited to 10 per
  minute per IP; a 429 means wait, not that you did something wrong.
- Markdown renderings are excluded from search indexes via robots.txt. They stay
  fetchable — that only affects crawler indexing, not access.