# bytEM

> A bytEM market indexes data entities and brokers access to them. Every entity
> is named by a DEID — a Data Entity Identifier, which is a resolvable URL owned
> by its domain, e.g. https://cities.app/de/he/eppstein. bytEM tells you which
> DEIDs exist, what quality their sources are, and how to obtain the data.

Four layers, in the order an agent uses them. The first two are open to anyone;
the last two identify the caller, because access to data is granted to someone,
not to no one.

| Layer    | Question                     | Identity needed |
| -------- | ---------------------------- | --------------- |
| INDEX    | What exists?                 | none            |
| DEID     | What is this entity?         | none            |
| FIND     | What can I access, and how?  | Matrix user     |
| EXCHANGE | Give me the actual data      | Matrix user     |

## Index — public, JSON, no JavaScript

- [Index summary](https://bytem.bm1.liberbyte.app/api/index/summary): total entries, the DEID pattern in
  use, per-region counts, the queryable fields, every endpoint with its
  parameters, and the identity each layer requires. Read this first.
- [List entries](https://bytem.bm1.liberbyte.app/api/index?limit=50&fields=deid,label,class,source_quality):
  the enumeration endpoint. Filters: deid, domain, class, group, depth,
  min_source_quality, max_source_quality, bbox, room_type, market_status.
  Paging: limit, offset. Projection: fields. Without limit it returns every
  match, so pass one unless you mean to pull the whole corpus.
- [Search entries](https://bytem.bm1.liberbyte.app/api/index/search?q=eppstein&limit=10&fields=deid,label):
  ranked lookup, same filters and projection, paged. Start with only deid and
  label; request more fields only when the task needs them.
- Map projection: [add location to the field list](https://bytem.bm1.liberbyte.app/api/index?limit=500&fields=deid,label,location)
  — there is no separate map endpoint and no separate map document.
- source_quality is a 0-100 assessment of the underlying source, produced by
  bytEM, not by the publisher. source_quality_status distinguishes scored,
  unavailable and failed from never assessed.

## DEID — public, JSON, served by the domain, not by bytEM

- A DEID resolves to its own document: [https://cities.app/de/he/eppstein](https://cities.app/de/he/eppstein)
  returns class, schema, label, location and any references. Fetch the DEID URL
  itself; it is JSON, and it is the entity's description.
- The DEID document is deliberately free of infrastructure. It never names a
  market, a room or an endpoint — which market carries an entity is answered
  here, by the index, and the markets are listed at
  [https://bytem.app/markets/bytem-market-list.json](https://bytem.app/markets/bytem-market-list.json).

## Find and Exchange — Matrix identity

- Find resolves one DEID to what is actually available: capabilities, access
  paths, service options, freshness. Exchange delivers the data or service
  result itself.
- Both identify the caller. Bring a Matrix user — on this homeserver, on
  matrix.org, or on one you run yourself. An agent with a Matrix ID has a name
  and a domain, and can be permitted, audited or blocked; that is the point.
- [How bytEM works](https://bytem.bm1.liberbyte.app/how-bytem-works) explains the ways in and what
  each one gets you.

## Notes for crawlers

- Rate limited per IP at the edge. Pass ?limit= and ?fields= rather than pulling
  everything; a 429 means slow down, not go away.
- https://bytem.app/room/room-index is the schema of a room's index entry — a
  template with empty values, not data. The data is at /api/index above.