--- name: critically description: >- Read and write research on Critically: notes backed by citations, organised into notebooks, with every cited page archived. Use when the user asks to look something up in their Critically account, add a note or a source, search their research, or pull a notebook out into another document. Trigger words: critically, critically.io, notebook, note, citation, cite a source, research board, archived source. user_invocable: true --- # Critically You are working with a research platform where a **claim** is the unit of work and everything hangs off whether it is **backed**. Your job is to help the user build a record that holds up, not to produce text that reads well. ## Important: what the words mean here - **Note**: one claim, 1500 characters at most. It lives in **many** notebooks at once, so adding it somewhere does not move it. - **Notebook**: an owned container with sections (columns) and members. - **Section**: a column inside a notebook. A note with no section is in "Loose notes", which is not a section. - **Citation**: points a claim at an archived page, or at another note. - **Stance**: `supports`, `refutes` or `contextualizes`. Dissent is first-class — a refuting citation sits in the same list as a supporting one. - **is_opinion**: means "no approved external source". It is about sourcing, never about truth. There are no likes, no upvotes, no reactions, and no score that stands in for whether something is true. Do not offer to add one, and do not summarise a note's standing as a single number. Report the distribution instead: how many support it, how many dispute it. ## The reference Every endpoint, parameter and refusal: https://critically.io/docs Why you would use it at all: https://critically.io/developers A six-step tour the user can run themselves: https://critically.io/settings/api/tour Read the reference rather than guessing at a parameter. It is short. ### Per-object detail Load the one you are working on. They are short and they say the things that are easy to get wrong. - A note: https://critically.io/skills/note.md - A notebook: https://critically.io/skills/notebook.md - A section: https://critically.io/skills/section.md ## Authentication The user issues a key at https://critically.io/settings/api and gives it to you. Send it as `Authorization: Bearer ` on every request. **Ask the user to tick "A model will hold this key" when they issue it.** It is the honest setting for you, and it changes what happens: sources you add wait for the user to accept them, even on their own notes. That is a feature and not an obstacle — it means nothing you propose becomes a claim they never read. A key acts as the user. It reaches exactly what they reach, so if something comes back empty it is because they cannot see it either, not because you have the wrong scope. --- ## Step 1: Work out what they are asking for Ask, if it is not already obvious: 1. **Find something** — search their notes and boards. 2. **Record something** — write a note and back it with a source. 3. **Take something out** — pull a notebook into a brief, a post, a filing. --- ## Path 1: Finding ```bash curl "https://critically.io/api/v1/search?q=TERM" -H "Authorization: Bearer $KEY" ``` Then read a note with what it rests on, which is one request and the one that matters: ```bash curl "https://critically.io/api/v1/notes/NOTE_ID" -H "Authorization: Bearer $KEY" ``` Each citation carries `archive_url`: the captured page, on Critically. Give the user that link rather than the original when the question is what the source said at the time — the original may have changed, and `has_changed` on the source tells you whether it has. **You cannot search the archive.** Captured page text is not available through the API by design. The way to an archive is the note that cites it. --- ## Path 2: Recording Write the claim first, then back it. A note with no approved source is marked `is_opinion`, which is accurate rather than a failure — say so to the user instead of hiding it. ```bash # 1. the claim curl "https://critically.io/api/v1/notes" -H "Authorization: Bearer $KEY" \ -H "content-type: application/json" \ -d '{"title":"...","body":"...","notebook_id":"OPTIONAL"}' # 2. what it rests on — this archives the page curl "https://critically.io/api/v1/citations" -H "Authorization: Bearer $KEY" \ -H "content-type: application/json" \ -d '{"note_id":"...","url":"https://...","stance":"supports","excerpt":"the quoted passage"}' ``` Send `excerpt` whenever you can. It is the passage being relied on, and it is what lets a reader check the claim against the page rather than taking the citation's word for it. **To disagree with an existing note, cite it with `stance: "refutes"`** and `target_note_id`. That is how dissent works here, and it surfaces on both notes rather than being a report or a flag. --- ## Path 3: Taking it out ```bash curl "https://critically.io/api/v1/notebooks/NOTEBOOK_ID" -H "Authorization: Bearer $KEY" ``` Returns the board, its sections and the notes on it. Lists page: send `next_cursor` back as `cursor` until it comes back null, or you will quietly summarise the first 25 of 300 notes. When you render their research somewhere else, carry the citations with it. A claim without its sources is the thing this platform exists not to produce. --- ## What the API will not do, and will not be talked into Do not design around these. They are decisions, not gaps, and the database enforces them rather than the client. - **It cannot publish.** Notes and boards you create are private, and `visibility` is not read from the request. If the user wants something public, tell them it is one press on the site and one-way. - **It cannot decide what the user has accepted.** Sources you add wait for them. Do not report a pending citation as done. - **It cannot hand over the archive.** You get the address, the publisher, whether the page has changed, and a link to the capture here. - **It cannot delete across other people's boards.** A note only its author holds can be deleted. A note sitting on somebody else's board cannot — the API answers 409 and names the alternative, which is to **abandon** it: the byline goes and the note stays where people put it. Do not describe abandoning as deleting. ## General behaviours - **Never state a claim the user has not seen as though it is theirs.** You draft; they sign. That is the whole posture of this product. - **Prefer one well-sourced note to five unsourced ones.** The count is not the point; `citation_count` and `dispute_count` are what anybody reads. - **Quote the passage you are relying on**, and say which source it came from, every time. - **If a page refuses to archive**, say so plainly. Roughly half of major publishers refuse an automated fetch, the worker falls back and records `quality`, and a citation that says it is blocked is worth more than one that pretends otherwise. - **Report rate limits rather than retrying blindly.** Every answer carries `X-RateLimit-Remaining`.