# Adventures With You — briefing for an assistant

https://adventureswithyou.com

Adventures With You is a record of what two people have done together and what
they want to do next. It is one workspace shared by two people, which is the
single most important thing to understand before writing anything into it.

## What is actually connectable today

Adventures With You does not serve an MCP endpoint, does not run an OAuth grant flow, and has no tool-grant screen. None of those exist in the code today, so nothing on this page offers to connect an assistant.

What is real is the REST surface described below: a versioned API with bearer keys. An integrator can use it now. A person cannot yet point their assistant at this site and have it connect itself.

A product-native MCP server is planned. When it exists, it will be described here — and not one sentence before.

## How to connect

- Transport: ordinary HTTPS REST. Base path /api/v1.
- Auth: Authorization: Bearer <api_key>. The Authorization header is the only one that works; there is no x-api-key.
- Key storage: SHA-256 hashed at rest; the plaintext key is shown once, at creation.
- Getting a key: POST /api/v1/auth/register. Creating a key needs a signed-in Adventures With You session (Clerk). An API key cannot mint another key.
- Managing keys: https://adventureswithyou.com/settings/api-keys — create, rename, rotate, revoke, set an expiry.
- On refusal: A 401 means the key is missing, revoked, expired or malformed — the person re-creates it at /settings/api-keys. A 403 means the key is real but its tier does not reach that endpoint.
- Errors arrive as { ok: false, error: { code, message, details, requestId } }.
- Writes accept an Idempotency-Key header, scoped to key + method + path + body hash.

## Access tiers

- Trial (trial) — Low-volume discovery and starter automation. Read-first access with small action budgets for first success and safe experimentation. Created: self-serve. Limits: 40/min, 1200/day, 75 writes/day.
- Standard (personal) — Default self-serve access for normal user and agent workflows. Can create and update data within normal user-owned and partnership-scoped endpoints. Created: self-serve. Limits: 300/min, 10000/day, 1000 writes/day.
- Trusted (contributor) — Trusted higher-throughput access for public content production. Can add and maintain public/shared items across all 8 Together API domains without other users' private records. Created: admin only. Limits: 800/min, 60000/day, 6000 writes/day.
- Admin / Operator (admin) — Full governance for platform operations, security, and support handoff. Can change key tiers, suspend API users, inspect audit logs, and rotate/revoke keys platform-wide. Created: admin only. Limits: 1000/min, 100000/day, 10000 writes/day.

## What this site assists the AI with

191 documented paths and 252 operations. The dictionary below is
generated from the live discovery index at /api/v1, cross-checked against
/openapi/openapi.v1.json; it is never written by hand.

Identity and keys (12):
  POST /api/v1/auth/register — Create API key (requires Clerk session; supports optional expiresAt)
  GET /api/v1/me — Shared alias for current user info + partnerships
  GET /api/v1/auth/me — Get current user info + partnerships
  GET /api/v1/usage — Get current key usage, limits, effective tier, and policy state
  GET /api/v1/access-matrix — API doctor: effective tier, preset readiness, endpoint access, and support handoff notes
  GET /api/v1/capabilities — Get machine-readable capability manifest
  GET /api/v1/openapi — Get OpenAPI v1 JSON spec
  GET /api/v1/auth/keys — List my API keys (optional includeDeleted=true)
  PATCH /api/v1/auth/keys/:id — Rename key and/or update expiration (expiresAt or null)
  DELETE /api/v1/auth/keys/:id — Soft-delete API key
  POST /api/v1/auth/rotate — Rotate API key
  DELETE /api/v1/auth/revoke — Revoke API key

Partnerships (3):
  GET /api/v1/partnerships — List my partnerships
  GET /api/v1/partnerships/:id/completions — Get completions for a partnership
  POST /api/v1/partnerships/:id/completions — Log a completion

Play (13):
  GET /api/v1/play/catalog — Browse game catalog (filters: category, subcategory, page, pageSize)
  GET /api/v1/play/catalog/search?q= — Search games
  GET /api/v1/play/list?partnershipId= — List gaming collection
  POST /api/v1/play/list — Add to gaming collection
  PATCH /api/v1/play/list/:id — Update gaming entry
  POST /api/v1/play/list/:id/record-play — Record a play session
  GET /api/v1/play/votes?partnershipId= — List game votes
  POST /api/v1/play/votes — Vote on a game
  GET /api/v1/play/matches?partnershipId= — Get matched games
  GET /api/v1/play/game-nights — List game nights
  POST /api/v1/play/game-nights — Create a game night
  POST /api/v1/play/game-nights/:id/games — Add a game to a night
  GET /api/v1/play/stats?partnershipId= — Gaming stats

Watch (11):
  GET /api/v1/watch/catalog/search?q= — Search movies/TV via TMDB
  GET /api/v1/watch/list?partnershipId= — List watchlist items
  POST /api/v1/watch/list — Add to watchlist
  GET /api/v1/watch/list/:id?partnershipId= — Get watchlist item
  DELETE /api/v1/watch/list/:id?partnershipId= — Remove from watchlist
  POST /api/v1/watch/list/:id/watched — Mark as watched
  POST /api/v1/watch/list/:id/heart — Set heart level
  POST /api/v1/watch/list/:id/seen-before — Set seen-before status
  POST /api/v1/watch/list/:id/rating — Set rating
  PATCH /api/v1/watch/list/:id/notes — Update notes
  GET /api/v1/watch/stats?partnershipId= — Watch stats

Read (13):
  GET /api/v1/read/catalog — Browse book catalog
  GET /api/v1/read/catalog/search?q= — Search books
  GET /api/v1/read/catalog/categories — List book categories
  GET /api/v1/read/list?partnershipId= — List reading entries
  POST /api/v1/read/list — Add to reading list
  PATCH /api/v1/read/list/:id — Update reading entry
  GET /api/v1/read/list/stats?partnershipId= — Reading stats
  GET /api/v1/read/votes?partnershipId= — List book votes
  POST /api/v1/read/votes — Vote on a book
  GET /api/v1/read/matches?partnershipId= — Get matched books
  GET /api/v1/read/lists — List curated book lists
  GET /api/v1/read/lists/:id — Get curated book list
  GET /api/v1/read/lists/slug/:slug — Get curated book list by slug

Listen (13):
  GET /api/v1/listen/catalog — Browse listen catalog
  GET /api/v1/listen/catalog/search?q= — Search listen catalog
  GET /api/v1/listen/catalog/categories — List listen categories
  GET /api/v1/listen/list?partnershipId= — List listening entries
  POST /api/v1/listen/list — Add to listening list
  PATCH /api/v1/listen/list/:id — Update listening entry
  DELETE /api/v1/listen/list/:id?partnershipId= — Remove listening entry
  GET /api/v1/listen/list/stats?partnershipId= — Listening stats
  GET /api/v1/listen/votes?partnershipId= — List listen votes
  POST /api/v1/listen/votes — Vote on a listen item
  GET /api/v1/listen/matches?partnershipId= — Get matched listen items
  GET /api/v1/listen/lists — List curated listen lists
  GET /api/v1/listen/lists/slug/:slug — Get curated listen list by slug

Activities (legacy alias) (1):
  GET /api/v1/grow/catalog — Legacy alias for Activities bucket-list discovery

Explore (27):
  GET /api/v1/explore/catalog — Browse explore locations (paginated)
  GET /api/v1/explore/items — List explore items
  POST /api/v1/explore/items — Create explore item
  GET /api/v1/explore/items/search?q= — Search explore items
  GET /api/v1/explore/items/:id — Get explore item
  PATCH /api/v1/explore/items/:id — Update explore item
  DELETE /api/v1/explore/items/:id — Remove explore item
  GET /api/v1/explore/places?partnershipId= — List places
  POST /api/v1/explore/places — Create place
  GET /api/v1/explore/places/:id?partnershipId= — Get place
  PATCH /api/v1/explore/places/:id — Update place
  DELETE /api/v1/explore/places/:id?partnershipId= — Remove place
  GET /api/v1/explore/activities?partnershipId= — List activities
  POST /api/v1/explore/activities — Create activity
  GET /api/v1/explore/activities/:id?partnershipId= — Get activity
  PATCH /api/v1/explore/activities/:id — Update activity
  DELETE /api/v1/explore/activities/:id?partnershipId= — Remove activity
  GET /api/v1/explore/day-trips?partnershipId= — List day trips
  POST /api/v1/explore/day-trips — Create day trip
  GET /api/v1/explore/day-trips/:id?partnershipId= — Get day trip
  PATCH /api/v1/explore/day-trips/:id — Update day trip
  DELETE /api/v1/explore/day-trips/:id?partnershipId= — Remove day trip
  GET /api/v1/explore/visits?partnershipId=&itemId=&limit= — List visits for a partnership
  POST /api/v1/explore/visits — Log a visit (requires partnershipId in request body)
  PATCH /api/v1/explore/visits/:id — Update a visit (requires partnershipId in request body)
  DELETE /api/v1/explore/visits/:id?partnershipId= — Remove a visit
  GET /api/v1/explore/visits/stats?partnershipId= — Visit stats for a partnership

Talk (10):
  GET /api/v1/talk/questions — Browse conversation questions
  POST /api/v1/talk/questions — Create a question
  GET /api/v1/talk/questions/:id — Get question
  PATCH /api/v1/talk/questions/:id — Update question
  DELETE /api/v1/talk/questions/:id — Remove question
  GET /api/v1/talk/questions/random — Get random question
  GET /api/v1/talk/questions/categories — List question categories
  POST /api/v1/talk/questions/:id/heart — Toggle question heart
  POST /api/v1/talk/questions/:id/discussed — Mark discussed
  DELETE /api/v1/talk/questions/:id/discussed — Unmark discussed

Activities (17):
  GET /api/v1/activities/templates?partnershipId=&subcategory= — List Activities templates with optional subcategory filter and partnership-scoped vote state
  GET /api/v1/activities/templates/categories?partnershipId= — Activities subcategories with partnership-scoped voted counts
  GET /api/v1/activities/templates/matches?partnershipId= — Matched templates for the active partnership
  POST /api/v1/activities/templates/vote — Vote on a template (requires partnershipId in request body)
  POST /api/v1/activities/templates/:id/add — Add template to projects (requires partnershipId in request body)
  GET /api/v1/activities/projects?partnershipId=&subcategory= — List Activities projects for a partnership
  POST /api/v1/activities/projects — Create partnership-scoped project
  GET /api/v1/activities/projects/:id?partnershipId= — Get project with tasks/updates for a partnership
  PATCH /api/v1/activities/projects/:id — Update project (requires partnershipId in request body)
  DELETE /api/v1/activities/projects/:id?partnershipId= — Remove project
  POST /api/v1/activities/tasks — Add project task (requires partnershipId in request body)
  PATCH /api/v1/activities/tasks/:id — Update task (requires partnershipId in request body)
  DELETE /api/v1/activities/tasks/:id?partnershipId= — Remove task
  POST /api/v1/activities/updates — Add project update (requires partnershipId in request body)
  PATCH /api/v1/activities/updates/:id — Update project update (requires partnershipId in request body)
  DELETE /api/v1/activities/updates/:id?partnershipId= — Remove project update
  GET /api/v1/activities/stats?partnershipId= — Project stats for a partnership

Dream (23):
  GET /api/v1/dream/lists?partnershipId= — List dream lists
  POST /api/v1/dream/lists — Create dream list
  GET /api/v1/dream/lists/:id?partnershipId= — Get dream list with stats
  PATCH /api/v1/dream/lists/:id — Update dream list
  DELETE /api/v1/dream/lists/:id?partnershipId= — Remove dream list
  GET /api/v1/dream/lists/:id/history?partnershipId= — List private dream-list change history
  POST /api/v1/dream/lists/:id/history — Record private dream-list change history
  GET /api/v1/dream/lists/:id/workspace — List private candidate workspace rows for items that should be in this bucket list
  POST /api/v1/dream/lists/:id/workspace — Import pasted/CSV/markdown candidate rows, including optional creatorNote and whyIncluded
  PATCH /api/v1/dream/lists/:id/workspace/:candidateId — Update a private candidate workspace row, including creatorNote, whyIncluded, sources, and match status
  GET /api/v1/dream/lists/stats?partnershipId= — Dream list stats
  GET /api/v1/dream/items?partnershipId= — List dream items
  POST /api/v1/dream/items — Create dream item; accepts notes or creatorNote
  PATCH /api/v1/dream/items/:id — Update dream item; accepts notes or creatorNote
  DELETE /api/v1/dream/items/:id?partnershipId= — Remove dream item
  POST /api/v1/dream/items/:id/toggle-complete — Toggle dream item complete
  POST /api/v1/dream/items/:id/move — Move dream item to list
  GET /api/v1/dream/templates — List dream templates
  GET /api/v1/dream/templates/:id — Get dream template with items
  GET /api/v1/dream/templates/categories — Dream template categories
  GET /api/v1/dream/templates/matches — Matched dream templates
  POST /api/v1/dream/templates/vote — Vote on a dream template
  POST /api/v1/dream/templates/add-to-lists — Add dream template to lists

Bucket lists (2):
  GET /api/v1/bucket-lists — List bucket list templates (filter: section)
  GET /api/v1/bucket-lists/:id — Get bucket list with items

Search (1):
  GET /api/v1/search?q=&sections=play,watch — Cross-section search

Catalog research (5):
  GET /api/v1/catalog/:section/:catalogTable/:catalogItemId/research — Get aliases, structured source evidence, and media assets for any canonical catalog item
  PUT /api/v1/catalog/:section/:catalogTable/:catalogItemId/research — Replace aliases, structured source evidence, and media assets for any canonical catalog item
  GET /api/v1/catalog/:section/:catalogTable/:catalogItemId/rich-content?contentType=learn_more — Get rich content such as Learn More About write-ups for any canonical catalog item
  PUT /api/v1/catalog/:section/:catalogTable/:catalogItemId/rich-content — Upsert rich content such as Learn More About write-ups for any canonical catalog item
  POST /api/v1/catalog/research/coverage — Return alias/source/media/Learn More coverage flags for a batch of catalog item targets

Owner and operator (46):
  GET /api/v1/admin/api-keys — List API keys + usage (admin)
  GET /api/v1/admin/access-requests — List API access escalation requests (admin)
  PATCH /api/v1/admin/access-requests/:id — Approve or deny an API access escalation request (admin)
  GET /api/v1/admin/stats — Advanced API key/admin analytics (admin)
  GET /api/v1/admin/operations/overview — Admin operations overview snapshot
  GET /api/v1/admin/operations/users — List users with API key and active-partnership diagnostics
  GET /api/v1/admin/operations/users/:id/diagnostics — Detailed diagnostics for a user
  PATCH /api/v1/admin/operations/users/:id/archive — Soft-archive or restore a user (admin)
  POST /api/v1/admin/operations/users/archive-likely-test — Soft-archive likely test users in bulk (admin)
  GET /api/v1/admin/operations/partnerships — Partnership health list with issue flags
  GET /api/v1/admin/operations/partnerships/:id — Partnership-level diagnostics and counts
  POST /api/v1/admin/operations/partnerships/:id/repair — Run a targeted partnership repair action (admin)
  GET /api/v1/admin/integrity/bucket-list — Bucket-list integrity report and recent run history
  POST /api/v1/admin/integrity/bucket-list — Run bucket-list integrity audit/repair pipeline
  GET /api/v1/admin/catalog-quality/hygiene-issues — Summarize catalog-research hygiene issues (placeholder licenses, wikimedia mistagged as institutional, non-canonical verifiedFields, tracking-param URLs, generic credits, Commons thumbnail URLs); pass ?gap=<name> for the per-item list, ?section=<name> to scope by Together section
  GET /api/v1/admin/bucket-list-research/production-queue — Summarize bucket-list production stages from proposed ideas through candidate matching, catalog creation, image/source audit, legacy audit, and release readiness
  GET /api/v1/admin/bucket-list-research/:id/history — List public bucket-list template change history
  POST /api/v1/admin/bucket-list-research/:id/history — Record public bucket-list template change history
  GET /api/v1/admin/bucket-list-research/:id/workspace — List public template candidate workspace rows
  POST /api/v1/admin/bucket-list-research/:id/workspace — Import public template candidate workspace rows from pasted/CSV/markdown source text
  PATCH /api/v1/admin/bucket-list-research/:id/workspace/:candidateId — Update a public template candidate workspace row, including creatorNote, whyIncluded, sources, and match status
  POST /api/v1/admin/bucket-list-research/:id/workspace/resolve — Resolve public template candidate rows in bulk: exact match, append linked, mark needs create, reject, reset, or full pass
  POST /api/v1/admin/bucket-list-research/:id/workspace/:candidateId/resolve — Resolve one public template candidate row
  POST /api/v1/admin/bucket-list-research/:id/items/append — Append canonical catalog-linked rows to a public bucket-list template; accepts creatorNote and whyIncluded
  PUT /api/v1/admin/bucket-list-research/:id/items — Replace public bucket-list template items with canonical catalog-linked rows; accepts creatorNote and whyIncluded
  GET /api/v1/admin/bucket-list-ideas — List admin-only rough bucket-list ideas before they become public templates
  POST /api/v1/admin/bucket-list-ideas — Create an admin-only rough bucket-list idea
  PATCH /api/v1/admin/bucket-list-ideas/:id — Update an admin-only bucket-list idea status or metadata
  DELETE /api/v1/admin/bucket-list-ideas/:id — Archive an admin-only bucket-list idea
  GET /api/v1/admin/ai-research/tasks/next — Generate and fetch the next AI research task by priority
  POST /api/v1/admin/ai-research/tasks/:id/claim — Claim an AI research task with a TTL
  POST /api/v1/admin/ai-research/tasks/:id/heartbeat — Extend an AI research task claim
  POST /api/v1/admin/ai-research/tasks/:id/complete — Complete an AI research task and record the result
  POST /api/v1/admin/ai-research/tasks/:id/block — Block an AI research task with a reason, optional packet, and next eligible time
  GET /api/v1/admin/ai-research/packets — List replayable AI research packets
  POST /api/v1/admin/ai-research/packets — Store a replayable AI research packet when research cannot be applied immediately
  GET /api/v1/admin/ai-research/packets/:id — Read one replayable AI research packet
  POST /api/v1/admin/ai-research/packets/:id/replay — Replay a packet into candidate workspace rows before starting new research
  PATCH /api/v1/admin/api-keys/:id — Update API key tier (admin)
  DELETE /api/v1/admin/api-keys/:id — Revoke API key (admin, default mode=revoke)
  DELETE /api/v1/admin/api-keys/:id?mode=delete — Soft-delete API key (admin)
  POST /api/v1/admin/api-keys/:id/force-rotate — Force-rotate API key and return replacement key (admin)
  GET /api/v1/admin/audit-logs — Query API activity logs (admin)
  GET /api/v1/admin/security-events — Filterable security event feed plus risk summary (admin)
  PATCH /api/v1/admin/users/:id/api-access — Suspend or restore all API access for a user (admin)
  PATCH /api/v1/admin/users/:id/tier-override — Set or clear user-level API tier override (admin)

## What this site assists the person with

- Keep the record of what you have done together: A visit becomes a memory: when you went, where, photos, and each person's own rating, note and return intent. Two people, two opinions, never averaged into one.
- Hold what you want to do next: Hearts mark what a person wants. Two hearts on the same thing is a match, read from the rail rather than stamped on a card. Pass retires something from suggestions without erasing it.
- Browse a shared catalog of things to do: Places, activities, films, books, listening, games, conversation questions and bucket lists — editorial content the site publishes, common to everyone.
- Plan a trip the two of you are actually taking: A private trip workspace with days and stops. Stops reference catalog items rather than copying them, so the catalog stays canonical.
- See a home page derived from all of it: Next up, Ready this week, Unfinished, Last time out, Waiting on each other. Every block is derived; a block with nothing true in it does not render.

## The vocabulary

- Partnership: The two-person workspace. Almost every private record is scoped to one, and a person can belong to more than one over a life.
- Catalog item: A canonical thing to do, watch, read, listen to, play or talk about. Shared by everyone, owned by nobody, and never containing a person's data.
- Bucket list: A published list of catalog items, or a partnership's own private list. The public ones are editorial; the private ones belong to the two people.
- Memory: The evidence that something happened, always attached to an item. Carries each person's own rating, note and return intent, plus partnership-private photos.
- Heart / Pass: One person's wanting, or one person's declining. A double heart is one person especially keen. A Pass retires an item from suggestions and keeps the record.
- Completion: A check. One person's check is one-sided; a together check exists only when both people mark it. The site never invents the second one.
- Trip: A private workspace at /our-trips with days and stops. Distinct from /trips, which is the public day-trip catalog.

## Rules of conduct

An assistant here may research, draft, enrich and organise. It may never do any
of the following, and no tier, key or setting changes that:

- Never mark a completion — not one person's check, and certainly not a together check.
- Never heart, double-heart or Pass anything. Wanting is a person's, not an assistant's.
- Never set a rating.
- Never write, edit or delete a memory, a private note or a return intent.
- Never message either person as the other, and never act as one of them.
- Never spend money, book, reserve or submit anything. This site transacts on nobody's behalf.
- Never make a decision that belongs to the relationship.

Working rules:

- Read before you write. The catalog is canonical; check whether a thing already exists before creating a second copy of it.
- Ask rather than assume. If the person's intent is unclear, say so and stop — there is no queue to park an assumption in.
- Do not promote a guess to a sourced fact. Research endpoints keep sources and evidence separate from claims for a reason.
- Stay inside the partnership the key's owner belongs to. Every private read and write is partnership-scoped and the server enforces it.
- Reuse an Idempotency-Key only when retrying the exact same write.
- Respect a 429. The response carries x-ratelimit-* and retry-after headers; wait rather than retrying immediately.

## First things worth doing

1. Call GET /api/v1 to read the live discovery index, then GET /api/v1/openapi for the full contract.
2. Call GET /api/v1/me to learn who the key belongs to and which partnerships they are in. Every private call needs a partnershipId from that response.
3. Call GET /api/v1/usage to see the key's tier, limits and remaining budget before planning a batch of work.
4. Browse something real — GET /api/v1/explore/catalog or GET /api/v1/bucket-lists — so you are talking about items that exist rather than inventing names.
5. Offer to research and draft: fill in a catalog item's detail, write a guide, tidy a taxonomy, or shape a trip. That is the work this site actually wants from an assistant.

## What stays here

Records belong to the partnership that made them and never move to another site. Memory photos are partnership-private: they never become an item's picture, never enter the public catalog, and never appear in any shared media surface. Deleting is not something this product does to a memory — a Pass retires a suggestion; the record of what happened stays.

## If you are asked how to contact us

Adventures With You has no support inbox, and an assistant must never offer, invent or infer an email address for this site — not support@, not contact@, not anything built from the domain. Send the person to the contact page at /contact, which says what is actually true about reaching us.

## More

- /ai.txt — This same briefing as plain text, for an assistant that reads badly through layout.
- /docs/agent-onboarding.md — The long-form written introduction to working against this API.
- /docs/agent-skill-pack.v1.json — A machine-readable pack of the workflows this site supports.
- /.well-known/api-capabilities.json — Auth shape, error envelope, rate-limit headers, idempotency rules and tier limits.
- /openapi/openapi.v1.json — The full contract — 191 paths, 252 operations.
- /api/v1 — The live discovery index this page's endpoint dictionary is built from.
- Human-readable version of this briefing: https://adventureswithyou.com/ai