Your AI
Bringing your AI to Adventures With You
This page has two readers. The first half is for you. The second half is written for your assistant, so you can paste this address into a chat and let it read the rest itself.
The short version
Adventures With You works completely without an AI. Everything below is optional, and nothing on this page changes what the site does for the two of you.
What exists today is a full REST API with personal keys. If you write software, or you use an assistant that can call a web API with a key you give it, it can read the catalog, help fill in detail, and help shape a trip. You create a key at /settings/api-keys while signed in, and you can rename, rotate or revoke it there at any time.
There is no MCP connection here yet
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.
What an AI can never touch here
This is the part worth reading even if you never bring one. An assistant is allowed to research, draft, enrich and organise. It is not allowed to have an opinion about your life, and that boundary is enforced by the absence of the tools rather than by a switch you could flip by accident:
- 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.
Your hearts, your Passes, your ratings, your private notes and your memories stay yours. A record of what two people felt about a place is worth nothing the moment something else can write into it.
If you change assistants later
Nothing moves with it. Your records, lists, memories and trips live here, and a new assistant picks them up with a new key on its first day. Revoking a key at /settings/api-keys stops that assistant immediately and deletes none of your own work.
Part of the Assist With family
Adventures With You is its own product with its own name, and it is also part of the Assist With family — which is where the shape of this page comes from. The family row in the footer is the whole roster. Data never crosses between those sites.
Below this line
The briefing for your assistant
Everything from here down is written for a machine to read literally. The same text is served as plain text at /ai.txt, which is the better address to hand an assistant that reads pages badly.
Part one
How to connect
- Transport. Ordinary HTTPS REST. Base path
/api/v1. There is no socket, no session and no handshake. - Auth.
Authorization: Bearer <api_key>. TheAuthorizationheader is the only one that works —x-api-keyis not supported anywhere. - 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.
/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. Every failure returns
{ ok: false, error: { code, message, details, requestId } }. - Retries. Writes accept an
Idempotency-Keyheader, scoped to key + method + path + body hash.
Access tiers
| Tier | What it reaches | Created | Per day |
|---|---|---|---|
| Trial | Read-first access with small action budgets for first success and safe experimentation. | Self-serve | 1,200 calls, 75 writes |
| Standard | Can create and update data within normal user-owned and partnership-scoped endpoints. | Self-serve | 10,000 calls, 1,000 writes |
| Trusted | Can add and maintain public/shared items across all 8 Together API domains without other users' private records. | Admin only | 60,000 calls, 6,000 writes |
| Admin / Operator | Can change key tiers, suspend API users, inspect audit logs, and rotate/revoke keys platform-wide. | Admin only | 100,000 calls, 10,000 writes |
Part two
What this site assists the AI with
191 documented paths, 252 operations, 197 of them named in the index below. This dictionary is generated from the live index at GET /api/v1, cross-checked against the OpenAPI document — it is not maintained by hand and cannot fall behind the routes.
Identity and keys12
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
Partnerships3
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
Play13
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
Watch11
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
Read13
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
Listen13
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
Explore27
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
Talk10
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
Activities17
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
Dream23
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 lists2
GET /api/v1/bucket-lists
List bucket list templates (filter: section)
GET /api/v1/bucket-lists/:id
Get bucket list with items
Search1
GET /api/v1/search?q=§ions=play,watch
Cross-section search
Catalog research5
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 operator46
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)
Part three
What this site assists the person with
The jobs in the order people actually hit them. Written to be paraphrased back to the person rather than recited.
- 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.
Part four
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.
Part five
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.
Part six
First things worth doing
- Call GET /api/v1 to read the live discovery index, then GET /api/v1/openapi for the full contract.
- 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.
- Call GET /api/v1/usage to see the key's tier, limits and remaining budget before planning a batch of work.
- 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.
- 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.
Boundary
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.
Boundary
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.
Reference
Everything else an agent can read
- /ai.txt
This same briefing as plain text, for an assistant that reads badly through layout.
- Agent onboarding guide
The long-form written introduction to working against this API.
- Agent skill pack (JSON)
A machine-readable pack of the workflows this site supports.
- Capability manifest
Auth shape, error envelope, rate-limit headers, idempotency rules and tier limits.
- OpenAPI 3.1 document
The full contract — 191 paths, 252 operations.
- GET /api/v1
The live discovery index this page's endpoint dictionary is built from.