Help & API

The idea

nearCited is a personal research and citation locker. You save cards — links, images, tweets, quotes and notes — and organise them two ways at once:

  • Topics are nested folders, e.g. Iraq → War → Politics. A card can live in many topic nodes at once.
  • Tags are flat, cross-cutting labels like #saddamhussein or #primarysource.

So one Saddam Hussein quote can sit under Iraq → Politics → Religion, Religion → Islam, and the tag #saddamhussein — and you can reach it through any of those routes.

FAQ

How fast is adding a card?

Press n anywhere, paste a URL, and nearCited fetches the title, image and source for you. Add topics/tags in the same box and save. Faster than bookmarking.

How do I find things later?

Open a topic and use the filter bar, follow a tag, or press / to search everything (titles, content, notes, speakers, sources).

What does “public” mean?

Marking a topic public exposes only that topic's own cards at https://nearcited.defy.network/u/<username>/<topic>. Subtopics appear only if they are public too. Private cards never show.

Can I get my data out?

Yes — Settings → Export downloads everything as JSON.

Keyboard shortcuts

n Quick Add · / focus search · Esc close dialogs.

REST API

The API powers the (future) browser extension and any scripts you write. Create a token under Settings → API tokens; it is shown once. Send it as a bearer token:

Authorization: Bearer nck_xxxxxxxxxxxxxxxxxxxxxxxx

Base URL: https://nearcited.defy.network/api. All requests and responses are JSON. Errors use {"error": {"code": "...", "message": "..."}}.

MethodEndpointPurpose
GET/api/meCurrent user (setup sanity check)
GET/api/topicsFull topic tree (nested)
GET/api/tagsAll tags
GET/api/suggest?q=Combined topic + tag autocomplete
POST/api/cardsCreate a card (supports fetch_url + base64 image)
GET/api/cards?topic_id=&tag=&q=&type=List / search cards
GET/api/cards/{id}Fetch one card
PATCH/api/cards/{id}Update a card
DELETE/api/cards/{id}Soft-delete a card

Example: create a link card with server-side scraping

curl -X POST https://nearcited.defy.network/api/cards \
  -H "Authorization: Bearer nck_xxx" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "link",
        "source_url": "https://example.com/article",
        "fetch_url": true,
        "new_tags": ["primarysource"],
        "topic_ids": [3]
      }'

Full request/response examples are in API.md in the project root.

Browser extension (coming soon)

The extension will use this same API to save the current page in one click. Add its origin to cors_allowed_origins in config.php to enable it.