1
specimen
Interitio edited this page 2025-06-18 19:33:50 +10:00

Specimen

Represents a specimen, remembered or forgotten.

field type required description
specimen_id integer - UID of this specimen
owner_id integer yes (Internal) id of the user who owns this specimen
owner User no User who owns this specimen
born_at timestamp no When this specimen came into existence. Will be set to now if not given.
forgotten_at timestamp? no When this specimen was forgotten.
  • POST /specimens
    • Create and return a new Specimen .
    • The owner may be specified in place of the owner_id. In this case it should be in the form of a User (as in POST /user).
      • Supplying both an owner_id and owner is not supported.
      • If an owner object is supplied and a User already exists with the given twitch_id, then that User will instead be updated with the given fields, and the user_id of the existing User will be used as the owner_id of the created Specimen.
  • GET /specimens
    • Returns Specimens matching the provided filters.
    • Supported filter parameters:
      • specimen_id
      • owner_id
      • born_after
      • born_before
      • forgotten - boolean, filters by whether forgotten_at is set.
      • forgotten_after
      • forgotten_before
  • GET /specimens/{specimen_id}
    • Get the Specimen with the given id.
  • PATCH /specimens/{specimen_id}
    • Updates the given Specimen
    • Supports updating owner_id and forgotten_at
  • DELETE /specimens/{specimen_id}
    • Deletes and returns the given Specimen
  • * /specimens/{specimen_id}/owner
    • Inherits all routes from the /users/{user_id} route with the associated owner_id.

// Notably, the inheritance allows a lot of cyclic references. You can for example do GET /events/1/user/specimen/owner/specimen/user/... and obtain the expected response. Each level adds the relevant filter parameter or overwrites it if the parameter is already set.