{"title":"Keeplore agent API","base_url":"https:\/\/api.staging.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 or search items in the key's collection.","body_fields":["page","per_page","query","cursor","tag"],"example_body":"{\"page\":1,\"per_page\":50}","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.","The list returns id, Title, and tags. Fetch one item for kept, secondary collection, physical, digital, and the rest of the record.","tag filters to items the owner labelled with that tag (for example beach-safe).","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."]},{"id":"list-uses","method":"GET","path":"\/uses.php","summary":"List recorded uses for the key's user.","query_fields":["artifact_id"],"example_query":"?artifact_id=123","notes":["Omit artifact_id to list every use. A use is an actual interaction, not an item proposal."]},{"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."]}]}