Universes¶
List Universes¶
GET /universes
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Successful Response | UniverseCollection |
Also the shared errors: 400, 401, 404, 405, 422, 500, 501, 503.
Create Universe¶
POST /universes
Request body: UniverseCreate
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Successful Response | Universe |
Also the shared errors: 400, 401, 404, 405, 422, 500, 501, 503.
Get Universe¶
GET /universes/{universe_id}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
universe_id |
path | string | yes | Letters, digits, dash and underscore; up to 64. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Successful Response | Universe |
Also the shared errors: 400, 401, 404, 405, 422, 500, 501, 503.
Put Universe¶
PUT /universes/{universe_id}
Replace a universe, repairing an unreadable one if that is what it is.
A PUT carries a complete valid replacement, so over an unreadable
document it is a repair — and the read-only check cannot run, because
source is one of the fields the server cannot read. Refusing would
leave the document unfixable through the API, the same trap the delete
had (BN-177), so the check is skipped and logged. It is not skipped
for a document that reads: that is the whole point of it.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
universe_id |
path | string | yes | Letters, digits, dash and underscore; up to 64. |
Request body: UniverseUpsert
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Successful Response | Universe |
| 409 | The universe was seeded from the dataset and is read-only. | ErrorEnvelope |
Also the shared errors: 400, 401, 404, 405, 422, 500, 501, 503.
Delete Universe¶
DELETE /universes/{universe_id}
Remove a universe, whether or not the server can read it.
Removal needs the file to be PRESENT, not valid, so this asks existence and not readability (BN-177). Going through a strict read made an unreadable universe 500 here, which left the id occupied forever — only deleting the file on the server could clear it.
The read-only check is skipped when the document cannot be read: you cannot protect the contents of a file you cannot read, and refusing would leave it permanently undeletable, which is strictly worse than the risk it guards against. A seeded universe can be regenerated; a stuck id cannot be cleared through the API at all.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
universe_id |
path | string | yes | Letters, digits, dash and underscore; up to 64. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Successful Response | |
| 409 | The universe was seeded from the dataset and is read-only. | ErrorEnvelope |
Also the shared errors: 400, 401, 404, 405, 422, 500, 501, 503.
Get Members¶
GET /universes/{universe_id}/members
The members, re-evaluating the filter when the universe is live.
This is where the frozen/live distinction becomes observable: a frozen universe answers with what it stored, a live one answers with what its filter selects now. Both are legitimate; a universe that looked like one and behaved like the other would not be.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
universe_id |
path | string | yes | Letters, digits, dash and underscore; up to 64. |
date |
query | string or null | no | Date to resolve a live filter at, YYYY-MM-DD. Defaults to the end of the loaded data. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | Successful Response | UniverseMembers |
Also the shared errors: 400, 401, 404, 405, 422, 500, 501, 503.