API

Programmatic access to the Equation 677 database.

Authentication

All write endpoints (POST) require authentication by one of the following methods.

Browser session. Sign in at /auth/github; subsequent same-origin requests carry the session cookie.
Bearer token. Generate one from your profile while signed in. Send it on every request:
```
Authorization: Bearer <your-token>
```
Tokens are 160-bit secrets prefixed with eq677_. They don't expire on their own; revoke from your profile.

Unauthenticated reads are always allowed.

Hash arguments

Each isomorphism class is identified by the SHA-256 (64 hex chars) of its canonical Cayley table. Anywhere a :hash appears in a route you can supply any prefix that uniquely identifies a single magma — e.g., /magma/abcd1234 resolves to the full canonical hash. HTML routes redirect to the canonical URL, which uses the first 32 hex chars (128 bits) of the full hash; that prefix is more than enough to be globally unique. API JSON responses always include the full 64-char canonical_hash.

POST /submit

Submit a candidate magma. The body is the Cayley table, in either of two formats:

Plain text (Content-Type: text/plain): n rows of n non-negative integers (each < n), whitespace- or comma-separated.
JSON array (Content-Type: application/json): a top-level array of arrays of integers, e.g. [[0,1],[1,0]].

The server canonicalizes the table and stores the isomorphism class.

Auth: required

Response (200, JSON):

{
  "id": 42,
  "canonical_hash": "ab12...",
  "size": 5,
  "satisfies_255": true,
  "right_cancellative": false,
  "idempotent": false,
  "fresh": true
}

Errors: 400 (parse), 401 (no auth), 415 (wrong Content-Type), 422 (table doesn't satisfy Equation 677 — response includes a witness {x, y}), 502 (canonicalizer failure).

$ curl -X POST https://eq677.icarm.cloud/submit \
       -H 'authorization: Bearer eq677_<token>' \
       -H 'content-type: text/plain' \
       --data-binary @table.txt

$ curl -X POST https://eq677.icarm.cloud/submit \
       -H 'authorization: Bearer eq677_<token>' \
       -H 'content-type: application/json' \
       -d '[[0,4,3,2,1],[3,1,4,0,2],[1,0,2,4,3],[4,2,1,3,0],[2,3,0,1,4]]'

POST /magma/:hash/comment

Replace the magma's current comment. Each call appends an entry to the comment history.

Auth: required
Max content: 4096 characters
Empty content clears the comment (still logged as a clear edit)
When rendered, tokens of the form magma#<hex> (1–64 lowercase hex chars) become links to /magma/<hex>. No other markup is interpreted; everything else is escaped as plain text.

JSON form (Content-Type: application/json):

{ "content": "this is a quasigroup" }

Returns:

{
  "canonical_hash": "ab12...",
  "comment_id": 17,
  "content": "this is a quasigroup"
}

Form-encoded (application/x-www-form-urlencoded): content=... — on success, redirects (302) to /magma/:hash.

$ curl -X POST https://eq677.icarm.cloud/magma/ab12/comment \
       -H 'authorization: Bearer eq677_<token>' \
       -H 'content-type: application/json' \
       -d '{"content":"left-cancellative quasigroup of order 5"}'

POST /size/:n/comment

Replace the size-level commentary for size :n (an integer in [1, 1000]). Each call appends an entry to the size-comment history; sizes without any submitted magmas may still be commented on.

Auth: required
Max content: 4096 characters
Empty content clears the commentary (still logged as a clear edit)
When rendered, tokens of the form magma#<hex> (1–64 lowercase hex chars) become links to /magma/<hex>. No other markup is interpreted; everything else is escaped as plain text.

JSON form (Content-Type: application/json):

{ "content": "no example known of this size yet" }

Returns:

{
  "size": 5,
  "comment_id": 9,
  "content": "no example known of this size yet"
}

Form-encoded (application/x-www-form-urlencoded): content=... — on success, redirects (302) to /size/:n.

$ curl -X POST https://eq677.icarm.cloud/size/5/comment \
       -H 'authorization: Bearer eq677_<token>' \
       -H 'content-type: application/json' \
       -d '{"content":"no example known of this size yet"}'

POST /magma/:hash/display-reorder

Set the visualization permutation σ used when rendering this magma's image. The canonical labeling is unchanged; the reorder is display-only and tracked in a separate history. Each call appends to that history.

Auth: required
Format: comma-separated permutation of [0, n) — e.g. 0,3,1,2,4. null (or empty form value) means identity.

JSON form:

{ "display_reorder": "0,3,1,2,4" }
{ "display_reorder": null }

Returns:

{
  "canonical_hash": "ab12...",
  "display_reorder": "0,3,1,2,4"
}

Form-encoded: display_reorder=0,3,1,2,4 (or empty). Redirects to /magma/:hash/reorder-history.

$ curl -X POST https://eq677.icarm.cloud/magma/ab12/display-reorder \
       -H 'authorization: Bearer eq677_<token>' \
       -H 'content-type: application/json' \
       -d '{"display_reorder":"0,3,1,2,4"}'

Useful read endpoints

GET /manifest.json — full list of magmas with metadata and a direct R2 download URL for each, plus a size_commentary array of {size, comment} pairs for every size whose current commentary is non-empty.
GET /magma/:hash/table.txt — the canonical Cayley table as plain text.
GET /magma/:hash/image.png — rendered PNG. Optional ?reorder=<value> overrides the stored permutation; ?reorder= (empty) renders identity.
GET /magma/:hash/comment-history — commentary edit history.
GET /magma/:hash/reorder-history — display-reorder edit history.
GET /size/:n/comment-history — size-level commentary edit history.