{"title":"Keeplore agent API","base_url":"https:\/\/api.keeplore.app","auth":{"scheme":"Bearer","header":"Authorization: Bearer <agent-key>","issue_path":"\/settings\/agent-keys.php","token_prefix":"ak_","scope":"reads plus the kept toggle"},"rate_limit":{"requests":60,"window_seconds":60},"denied_message":"Agent keys permit reads plus the kept toggle only.","endpoints":[{"id":"list-items","method":"POST","path":"\/artifacts.php","summary":"List, search, and filter items in the key's collection.","body_fields":["page","per_page","cursor","query","tag","kept","physical","digital","secondary_collection","type_id","fields","include"],"fields_values":["basic","collection"],"include_values":["uses_summary"],"example_body":"{\"kept\":true,\"type_id\":[26,39],\"physical\":true,\"fields\":\"collection\",\"include\":[\"uses_summary\"],\"per_page\":200}","get_lists_first_page":true,"notes":["Agent keys always read their own user; a userid in the body is ignored.","Default page size is 50; maximum is 200. has_more says whether another page exists. Send cursor (null, then next_cursor) to page by id instead of by title.","Every row carries id, Title, type, type_id, is_kept, is_physical, is_digital, is_in_secondary_collection, and tags.","kept, physical, digital, and secondary_collection take true or false. type_id takes one id or a list; ids come from GET \/types.php.","fields \"collection\" adds MnP, MxP, SS (sweet spot), MnT, MxT, Wt, Yr, and Acq.","include [\"uses_summary\"] adds plays (count of recorded uses) and last_use (YYYY-MM-DD or null).","tag filters to items the owner labelled with that tag (for example beach-safe). Tags are empty until the owner adds them, so an empty tag result does not mean no item fits.","Invalid filter values return 400 with an errors list.","GET with no body also lists page 1 for an agent key."]},{"id":"show-item","method":"GET","path":"\/artifact.php","summary":"Read one item by id, scoped to the key's user.","query_fields":["id"],"example_query":"?id=123","discovery_key":"GET \/artifact.php?id=<id>","notes":["Kept is is_kept. Secondary collection, physical, and digital are independent flags.","tags are the owner's free-form labels (portable, beach-safe, two-player, party). They complement player-count and time columns; they do not replace them. Most items have no tags yet, so expect an empty list."]},{"id":"list-uses","method":"GET","path":"\/uses.php","summary":"List recorded uses for the key's user.","query_fields":["artifact_id","player_id"],"example_query":"?player_id=45","notes":["Omit artifact_id to list every use. A use is an actual interaction, not an item proposal.","player_id keeps only uses that player took part in; ids come from GET \/players.php.","Each use carries players (deduplicated player ids) and participants (id, FirstName, LastName)."]},{"id":"list-players","method":"GET","path":"\/players.php","summary":"List the people recorded in the key's household.","query_fields":[],"notes":["Each player has id, name, FirstName, LastName, birth_year, and represents_user_id (set when the player is a Keeplore user)."]},{"id":"list-proposals","method":"GET","path":"\/proposals.php","summary":"Proposal outcome counts per item: explicit declines and chose something else.","query_fields":["start","end","include_other","sort","direction"],"sort_values":["item_name","explicit_declines","chose_something_else"],"example_query":"?start=2026-01-01&end=2026-12-31&sort=explicit_declines&direction=desc","notes":["start and end are YYYY-MM-DD. Default sort is explicit_declines descending.","By default the report covers kept items and the secondary collection. include_other=1 adds the rest.","Unsuccessful proposals do not count as uses and do not restart time since last use."]},{"id":"list-types","method":"GET","path":"\/types.php","summary":"List item types for the key's user.","query_fields":[],"notes":[]},{"id":"upcoming-interactions","method":"GET","path":"\/upcoming-interactions.php","summary":"Upcoming interact-by dates for kept items.","query_fields":[],"notes":["Interact-by dates come from recorded uses, not from proposal outcomes."]},{"id":"set-kept","method":"POST","path":"\/artifact-kept.php","summary":"Flip whether an item is kept. The only write an agent key may perform.","body_fields":["id","is_kept"],"example_body":"{\"id\":123,\"is_kept\":1}","is_kept_values":[0,1],"notes":["is_kept must be 0 or 1. This does not change secondary collection, physical, digital, tags, or to get rid of."]}]}