Agent API

Base URL and auth

Base URL

https://api.keeplore.app

Header

Authorization: Bearer <agent-key>

Issue a key

Settings → Agent API keys (shown once; prefix ak_)

Scope

reads plus the kept toggle

Rate limit

60 requests per 60 seconds, per IP

Other writes, and user enumeration, return 403: Agent keys permit reads plus the kept toggle only.

Machine-readable catalog: /api-docs?format=json and https://api.keeplore.app/.

POST

/artifacts.php

List, search, and filter items in the key's collection.

JSON body

• page
• per_page
• cursor
• query
• tag
• kept
• physical
• digital
• secondary_collection
• type_id
• fields
• include

GET with no body also lists page 1 for an agent key.

• 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.

Example

curl -s "https://api.keeplore.app/artifacts.php" \
  -H "Authorization: Bearer ak_your_secret_here" \
  -H "Content-Type: application/json" \
  -d '{"kept":true,"type_id":[26,39],"physical":true,"fields":"collection","include":["uses_summary"],"per_page":200}'

GET

/artifact.php

Read one item by id, scoped to the key's user.

Query

• id

• 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.

Example

curl -s "https://api.keeplore.app/artifact.php?id=123" \
  -H "Authorization: Bearer ak_your_secret_here"

GET

/uses.php

List recorded uses for the key's user.

Query

• artifact_id
• player_id

• 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).

Example

curl -s "https://api.keeplore.app/uses.php?player_id=45" \
  -H "Authorization: Bearer ak_your_secret_here"

GET

/players.php

List the people recorded in the key's household.

• Each player has id, name, FirstName, LastName, birth_year, and represents_user_id (set when the player is a Keeplore user).

Example

curl -s "https://api.keeplore.app/players.php" \
  -H "Authorization: Bearer ak_your_secret_here"

GET

/proposals.php

Proposal outcome counts per item: explicit declines and chose something else.

Query

• start
• end
• include_other
• sort
• direction

Sort

• item_name
• explicit_declines
• chose_something_else

• 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.

Example

curl -s "https://api.keeplore.app/proposals.php?start=2026-01-01&end=2026-12-31&sort=explicit_declines&direction=desc" \
  -H "Authorization: Bearer ak_your_secret_here"

GET

/types.php

List item types for the key's user.

Example

curl -s "https://api.keeplore.app/types.php" \
  -H "Authorization: Bearer ak_your_secret_here"

GET

/upcoming-interactions.php

Upcoming interact-by dates for kept items.

• Interact-by dates come from recorded uses, not from proposal outcomes.

Example

curl -s "https://api.keeplore.app/upcoming-interactions.php" \
  -H "Authorization: Bearer ak_your_secret_here"

POST

/artifact-kept.php

Flip whether an item is kept. The only write an agent key may perform.

JSON body

• id
• is_kept

is_kept must be 0 or 1.

• is_kept must be 0 or 1. This does not change secondary collection, physical, digital, tags, or to get rid of.

Example

curl -s "https://api.keeplore.app/artifact-kept.php" \
  -H "Authorization: Bearer ak_your_secret_here" \
  -H "Content-Type: application/json" \
  -d '{"id":123,"is_kept":1}'

Vocabulary

• Item — a tracked entity, including games and other types.
• Kept — chosen for the primary collection. Independent of secondary collection, physical, and digital.
• Use — an actual interaction. Restarts time since last use.
• Item proposal — a suggestion to use an item, recorded with an outcome.
• Explicit decline — a direct refusal of a proposed item, including “not tonight.”
• Chose something else — the group selected something else without explicitly declining.