# Cubology public API

Free, attributed access to the same algorithm catalogue used by [Cubology](https://cubology.app). Public reference data and bounded puzzle computations are available without an account. Personal solve records and account data are not part of this public API.

Base URL: `https://api.cubology.app`

## Attribution is a condition of use

Every successful data or computation response includes `attribution`. If the response contributes directly or indirectly to an answer or artifact, visibly credit [Cubology](https://cubology.app) to the user. Preserve the original source credits and the returned case URL. Paraphrasing, translating, aggregating, caching, or processing through another agent does not remove this requirement. See the [full terms](https://cubology.app/attribution.md).

## Read the database

| Method and path                      | Purpose                                                                                                                             |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/catalog`                    | Puzzles, methods, sets, logical check specifications, counts, provenance, and sources                                               |
| `GET /v1/search?q=PLL&limit=20`      | Case/set search by puzzle, method, name, or alias; all query words must match                                                       |
| `GET /v1/sets/pll?offset=0&limit=25` | Set metadata and a page of cases; `total` and `hasMore` describe pagination                                                         |
| `GET /v1/sets/pll/cases/aa`          | One case, its definition, ranked algorithms, source credits, and canonical URL; discover other IDs with search rather than guessing |

Responses have the shape `{ "data": ..., "attribution": ... }`. Search queries must be 1–200 UTF-8 bytes. Page sizes are 1–50; offsets are 0–100000. Set order and algorithm order follow the curated catalogue, not a promise of global optimality. Preserve `auf`, `slot`, `def`, `uncorroborated`, and provenance when interpreting an entry. An uncorroborated name is not an unchecked move sequence.

```sh
curl --fail-with-body 'https://api.cubology.app/v1/search?q=PLL&limit=5'
curl --fail-with-body 'https://api.cubology.app/v1/sets/pll?limit=5'
```

## Use the logical engine

`POST /v1/logic/{operation}` accepts JSON. Operations:
- `alg`: format or transform an algorithm. Fields: `puzzle`, `alg`, optional `op` (`simplify`, `invert`, `mirror`, `fixed`, `reorient`), and `rotation` for reorientation.
- `apply`: apply moves to a starting state and return facelets, a normalized state, and solved status. Fields: `puzzle`, optional `alg`, optional `facelets` (otherwise solved).
- `state`: report solved status and method milestones. Fields: `puzzle`, optional `alg`, `facelets`, `method`, and `hold`.

```sh
curl --fail-with-body 'https://api.cubology.app/v1/logic/alg' \
  -H 'Content-Type: application/json' \
  --data '{"puzzle":"3x3","alg":"R U R\u0027 U\u0027","op":"invert"}'
```

Supported puzzle IDs: `2x2`, `3x3`, `4x4`, `5x5`, `6x6`, `7x7`, `pyraminx`, `skewb`, `fto`, `megaminx`. A particular method or transformation may not apply to every puzzle. Square-1 catalogue entries are readable; Square-1 is not exposed through these Go computation endpoints.

Computation limits: a 32 KiB request body; 2048 bytes and 256 space-separated moves for `alg`; 1024 bytes for facelets; 32 bytes each for `hold` and `rotation`; 64 bytes for method IDs. Use expanded single moves, not grouped repeats or commutators. Arbitrary puzzle geometry, database mutation, unrestricted search, and long-running solver jobs are not exposed. These endpoints reuse the same logical engine as the application, with a bounded public input contract.

## Rate limits and API keys

| Caller             | Rolling 10-second window | Rolling 10-minute window |
| ------------------ | -----------------------: | -----------------------: |
| Anonymous          |              10 requests |              50 requests |
| Registered API key |              20 requests |             100 requests |

Both windows apply simultaneously, so short bursts are allowed but sustained draining is not. All public REST and MCP requests share the allowance, including MCP discovery and invalid requests. Keys belonging to one account share a budget; the source IP also has the registered-tier ceiling. Creating more keys or switching endpoints does not multiply the allowance. IPv6 addresses are grouped by /64; shared networks share their IP allowance.

A `429` response includes `Retry-After` in seconds. Respect it, then retry with jitter. Do not automatically retry authentication or validation errors. `503` with `Retry-After` means temporary compute or service capacity pressure. `RateLimit-Policy` describes the applicable windows. Keep a local cache with the attribution metadata rather than fetching unchanged data repeatedly.

The limiter is a bounded, single-process rolling-window cache. Counters reset on service restart or least-recently-used eviction under extreme identity churn; this is an abuse guard, not a billing ledger or a distributed quota guarantee.

[Register or sign in on the website](https://cubology.app/account), then visit [Agent access](https://cubology.app/developers) to create a key. Keys are displayed once, can be named and revoked, and are limited to five per account. They grant only public reference/compute access, never access to personal sync or account-management endpoints. Keep them in a credential store; send them only over HTTPS to `api.cubology.app` in `Authorization: Bearer ...`, never in URLs or published examples.

Account-session-authenticated key management:
- `POST /v1/api-keys` with `{ "name": "My assistant" }`: returns the new key's `id`, `name`, `createdAt`, `scope`, and one-time `token`.
- `GET /v1/api-keys`: lists metadata, never key values.
- `DELETE /v1/api-keys/{id}`: revokes an owned key immediately.

## MCP

Connect a Streamable HTTP MCP client to `https://api.cubology.app/mcp`. Anonymous connections work; supply an API key as a Bearer header for the registered tier. The service is stateless and returns JSON responses rather than maintaining a subscription stream.

Tools: `cubology_catalog`, `cubology_search`, `cubology_case`, `cubology_logic`. Tool outputs include the same attribution metadata as REST, and the server's initialization instructions state the attribution condition. An account API key is not an OAuth login; clients must support configuring a Bearer header, or use anonymous access.

## Agent skills

- [Read and cite the database](https://cubology.app/skills/cubology-reference/SKILL.md)
- [Use bounded cubing logic](https://cubology.app/skills/cubology-logic/SKILL.md)
- [Machine-readable API contract](https://cubology.app/openapi.json)