Skip to content
CEagle

What Roost is

The public program registry. Everything on it is readable without signing in.

Roost is where published programs live. It is a browsable site and an unauthenticated JSON API, and it is the only part of CEagle that anyone can read without an account.

Programs get there through Flight. Nothing publishes to Roost directly.

Browsing and search

Filters, sorting, paging and the category catalog.

Read on
The three download routes

Variable body, transfer file and developer archive — and which one you want.

Read on
Installing with dependencies

The procedure a client follows to write a program and everything it needs.

Read on
Keeping a calculator current

Reconcile a whole calculator in one request.

Read on

No sign-in#

There is no key to obtain and no header to send. Every endpoint under /api/v1 on Roost is public.

curl -s https://roost.ceagle.cc/api/v1/programs/snake

Addresses#

A program is identified by its slug, the address its project claimed and can never change.

That is what the program endpoint takes, what a dependency names, what a download URL contains, and what the bulk version check compares against.

Addresses and slugs

Why they are permanent.

Read on

What a program record carries#

{
  "slug": "snake",
  "title": "Snake",
  "summary": "The classic, on your calculator.",
  "language": "asm",
  "language_name": "ASM/C",
  "categories": ["games"],
  "tags": ["arcade", "classic"],
  "var_name": "SNAKE",
  "var_type": "program",
  "archived": false,
  "size": 14208,
  "size_text": "13.9 KB",
  "checksum": "3f9a…",
  "version": "1.2.0",
  "author": "Ada Lovelace",
  "status": "published",
  "downloads": 412,
  "raw_url": "/d/snake/raw",
  "file_url": "/d/snake",
  "filename": "snake.8xp",
  "dependencies": ["graphx-helpers"],
  "requires": []
}

Two fields do most of the work for a client:

checksum

A digest of the variable body. Compare it against what is on the calculator to decide whether to download at all.

requires

The flattened dependency list, deepest first. Present on the single-program endpoint so a client needs one request rather than two.

What is never returned#

Hidden programs

Downloadable at their address, but left out of listings, search and category counts.

Suspended programs

Belonging to an archived project. Filtered out of everything, including downloads and the dependency graph.

Both answer 404 on the endpoints that exclude them, rather than a distinct status, so a client cannot use the response to learn that a hidden program exists.

Roost API reference

Every endpoint, with schemas and live examples.

Read on
CEagle documentation