Skip to content
CEagle

Browsing and search

Filter, sort and page through the registry with one endpoint and five parameters.

GET/api/v1/programsPublic

One endpoint covers browsing, filtering and search. Filters combine.

curl -s "https://roost.ceagle.cc/api/v1/programs?category=games&sort=downloads&per_page=10"

Parameters#

Query
qstring

Free text. Matches the title, the summary and the address.

categorystring

A category key from the catalog. One at a time.

langbasic | asm | lib

The project language.

sortstringdefaults to newest

One of newest, oldest, downloads, title, size, updated. The live list is in the catalog response, so a client can build a menu from it rather than hard-coding these.

pageintegerdefaults to 1

Counting from 1.

per_pageinteger

Clamped to the maximum, so asking for a thousand quietly gives you the cap.

The response#

{
  "programs": [ /* … */ ],
  "total": 42,
  "page": 1,
  "per_page": 24,
  "pages": 2
}

Programs in a list come without their long description. Fetch a single program for that.

The catalog#

GET/api/v1/categoriesPublic

Everything a browse interface needs, in one call, with a live count against each category.

{
  "categories": [
    { "key": "games", "name": "Games", "description": "…", "restricted": false, "count": 42 }
  ],
  "languages": [
    { "key": "basic", "name": "TI-BASIC" },
    { "key": "asm", "name": "ASM/C" },
    { "key": "lib", "name": "LibLoad library" }
  ],
  "sorts": ["newest", "oldest", "downloads", "title", "size", "updated"],
  "total": 118
}

Counts move; the rest does not. Cache the shape and refresh the counts when you care.

One program#

GET/api/v1/programs/{slug}Public

The full record, including the long description and the flattened dependency list under requires.

A .8xp or .8xv suffix on the slug is tolerated and stripped, so a URL built by naively appending an extension still resolves.

What is excluded#

Hidden and suspended programs are never returned by any of these, and they are not counted in total or in a category count.

That means a category count can disagree with what a listing shows if you filter differently, but it can never reveal that a hidden program exists.

Search is not full text#

q matches the title, the summary and the address. It does not search the long description, tags or author.

That is worth knowing when writing a listing: the summary is the field carrying your discoverability, not the description.

CEagle documentation