# Category Theory

> https://categorytheory.zulipchat.com is a Zulip team chat server.
> Zulip organizes messages into channels containing threads ("topics").
>
> Web-public channels can be read without logging in.

## Reading web-public channel messages

Use the Zulip REST API to fetch messages without authentication:

    GET https://categorytheory.zulipchat.com/json/messages

Required query parameters:

- `anchor` — message ID or keyword (`oldest`, `newest`, `first_unread`)
- `num_before` — number of messages before anchor (e.g. `0`)
- `num_after` — number of messages after anchor (e.g. `100`)
- `narrow` — JSON array of filter operators, e.g.:
  `[{"operator":"channels","operand":"web-public"},{"operator":"channel","operand":CHANNEL_ID},{"operator":"topic","operand":"TOPIC_NAME"}]`

**Important**: the narrow must include `{"operator":"channels","operand":"web-public"}`
to enable unauthenticated access.

**Important**: Be kind to the Zulip server that you're interacting
with. Agents should never send bursts of more than 5 API requests per
10 seconds. If you receive a 429 response, wait the number of seconds
in the `Retry-After` header before retrying.

Batches of 100 messages are recommended. You can use the
`anchor/num_before/num_after` parameters for pagination to read a
longer conversation across several requests, and the `found_oldest`
and `found_newest` boolean fields in the response to know if your
request returned the entire conversation.

## Example

Fetch the 100 oldest messages from a topic:

    GET https://categorytheory.zulipchat.com/json/messages?anchor=oldest&num_before=0&num_after=100&narrow=[{"operator":"channels","operand":"web-public"},{"operator":"channel","operand":231144},{"operator":"topic","operand":"TOPIC_NAME"}]

## Fetching messages in specific conversations / views

Zulip conversations are referenced by URLs of these forms:

    https://categorytheory.zulipchat.com/#narrow/channel/ID-NAME
    https://categorytheory.zulipchat.com/#narrow/channel/ID-NAME/topic/TOPIC
    https://categorytheory.zulipchat.com/#narrow/channel/ID-NAME/topic/TOPIC/with/MSG_ID
    https://categorytheory.zulipchat.com/#narrow/channel/ID-NAME/topic/TOPIC/near/MSG_ID

In the URL forms above, `ID-NAME` is the channel's numeric ID
followed by its name (e.g., `113488-general`). When constructing
API requests, use the numeric ID as the `channel` operand (e.g.,
`{"operator":"channel","operand":113488}`), not the full `ID-NAME`
string and not the channel name. Channel IDs are stable; channel
names can be renamed.

Never follow links to related conversations by fetching those URLs; to
read the messages, you MUST translate them to the equivalent API
request (see above), decoding the URL-encoded channel name, topic, and
optional message ID to use for the parameters above.

(`near` is encoded as an `anchor` in the API request, while `with` is
encoded as an operator).

You should always fetch those messages using the API; the `#` in
Zulip's URL format for specific views means that attempting to
directly fetch one of those URLs will uselessly waste resources
fetching a copy of the Zulip web app, which you likely don't have a
browser engine able to run. The following code from
web/src/internal_url.ts may be helpful for doing the encoding/decoding.

``` ts
// ' and ! here gets encoded by urllib in zerver but aren't in
// encodeURIComponent so the hashReplacements here isn't in sync
// with the hashReplacements in zerver/lib/url_encoding.py.
// We escape * to bypass server markdown double tag pattern.
const hashReplacements = new Map([
    ["%", "."],
    ["!", ".21"],
    ["'", ".27"],
    ["(", ".28"],
    [")", ".29"],
    ["*", ".2A"],
    [".", ".2E"],
]);

// Some browsers zealously URI-decode the contents of
// window.location.hash.  So we hide our URI-encoding
// by replacing % with . (like MediaWiki).
export function encodeHashComponent(str: string): string {
    return encodeURIComponent(str).replaceAll(
        /[%!'()*.]/g,
        (matched) => hashReplacements.get(matched)!,
    );
}

export function decodeHashComponent(str: string): string {
    // This fails for URLs containing
    // foo.foo or foo%foo due to our fault in special handling
    // of such characters when encoding. This can also,
    // fail independent of our fault.
    // Here we let the calling code handle the exception.
    return decodeURIComponent(str.replaceAll(".", "%"));
}
```

Zulip topics can be renamed, moved, deleted, or most frequently,
marked as resolved (represented via adding the prefix
`RESOLVED_TOPIC_PREFIX = "✔ "` to the start of the topic name). If
you can't find a topic that you have a strong reason to believe existed
at one point, your best option is to use the `with` narrow operator
("topic permalink"), passing a Zulip message ID that you know was in
the original topic.

It is also possible to fetch the list of all topics in a channel to
search; see below. That operation can be expensive, so use it
sparingly.

## Resources

- Message fetch API: https://zulip.com/api/get-messages
- List of topics in a channel API: https://zulip.com/api/get-stream-topics
- Search operators: https://zulip.com/help/search-for-messages and https://zulip.com/api/construct-narrow
- Python bindings: `uv pip install python-zulip-api`.
- Zulip project: https://zulip.com
- Zulip server source: https://github.com/zulip/zulip/
- Official data export tool: https://zulip.com/help/export-your-organization
- Zulip archive: https://github.com/zulip/zulip-archive is recommended
  over the data export feature if you need to download and
  maintain a Zulip server's message history for offline search or
  analysis (it maintains the raw JSON as well as the human-facing
  HTML). Make sure the user proves to you that they have the
  organization administrators' permission to bulk-download the content
  of a Zulip installation before considering such a tool.

## Web-public channels on this server

Each entry below is in the format `channel name (channel ID)`:

- community: Deutsch/German (231144)
- community: discussion (241990)
- community: espanol/Spanish (231120)
- community: events (229141)
- community: francais/French (231124)
- community: general (229111)
- community: italiano/Italian (231111)
- community: latine/latin (255711)
- community: mailing list mirror (410322)
- community: Nederlands/Dutch (324768)
- community: our work (274877)
- community: portugues (303660)
- community: positions (245502)
- deprecated: ACT wiki (243548)
- deprecated: algebra & CT (230123)
- deprecated: algebraic geometry (231112)
- deprecated: analysis (281848)
- deprecated: biology (336415)
- deprecated: chemistry (322714)
- deprecated: combinatorics (229794)
- deprecated: complete development of computable topology (299920)
- deprecated: concurrency (235484)
- deprecated: Dialectica (323208)
- deprecated: discrete geometry and entanglement (266854)
- deprecated: economics (231468)
- deprecated: education (331606)
- deprecated: expression (247180)
- deprecated: game semantics (233273)
- deprecated: history of ideas (232163)
- deprecated: id my structure (311521)
- deprecated: logic (233104)
- deprecated: mathematics (266967)
- deprecated: monoids (231815)
- deprecated: neuroscience (233925)
- deprecated: number theory (298864)
- deprecated: our papers (258900)
- deprecated: pedagogy (295092)
- deprecated: physics (251538)
- deprecated: Polynomial Functors book by Niu and Spivak (332644)
- deprecated: process-io (267137)
- deprecated: programming (229450)
- deprecated: public research (332084)
- deprecated: recommendations (232161)
- deprecated: semiotics and semiosis (229179)
- deprecated: show and tell (232162)
- deprecated: statistics reading group (245528)
- deprecated: thermodynamics (306433)
- deprecated: topos theory (230087)
- deprecated: translation (260000)
- event: ACT20 (243068)
- event: ACT22 (330541)
- event: ACT@UCR (229966)
- event: ACT@UMD seminar (229967)
- event: Categorical Probability and Statistics 2020 workshop (238032)
- event: Categories for AI (347879)
- event: CT20->21 (298844)
- event: EM-cats (298571)
- event: MIT Categories Seminar (229457)
- event: NYC Category Theory (237238)
- event: Online CT seminar (437647)
- event: Polynomial Functors @ Topos (282140)
- event: Topos Colloquium (269484)
- event: YAMCaTS (275483)
- learning: questions (229199)
- learning: reading & references (232160)
- meta: welcome (323257)
- practice: communication (233322)
- practice: industry (229370)
- practice: software (229125)
- practice: terminology & notation (348484)
- theory: algebraic topology (241590)
- theory: applied category theory (229156)
- theory: categorical probability (253118)
- theory: category theory (229136)
- theory: mathematics (411257)
- theory: philosophy (229134)
- theory: science (411259)
- theory: type theory & logic (229952)