Agent API

Base URL and auth

Base URL

https://api.staging.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.staging.keeplore.app/.

POST

/artifacts.php

List or search items in the key's collection.

JSON body

• page
• per_page
• query
• cursor
• tag

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

Example

curl -s "https://api.staging.keeplore.app/artifacts.php" \
  -H "Authorization: Bearer ak_your_secret_here" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"per_page":50}'

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.

Example

curl -s "https://api.staging.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

• Omit artifact_id to list every use. A use is an actual interaction, not an item proposal.

Example

curl -s "https://api.staging.keeplore.app/uses.php?artifact_id=123" \
  -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.staging.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.staging.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.staging.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.staging.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.