# DeepDrive

> A thinking partner for your ideas. A person keeps a private list of topics, talks each one through with an AI partner by voice or text, and keeps a short summary of where they left off.

DeepDrive is operated by BusyMonkeys. Each person's topics, ratings, and session summaries are private. An assistant that was given only https://deepdrive.app should use this file. A personal API token from Settings is sent as `Authorization: Bearer dd_...`.

## What a conversation is

A topic is one thing worth talking through, on a walk, at a desk or in the car. A conversation has four beats:

1. Opening prompt. A thinking partner: one question at a time, conversational, challenge one assumption, then a fixed summary when the person wraps up.
2. Continue prompt. The same rules, plus the latest session summaries, so the next drive starts where the last one ended.
3. Wrap-up prompt. Asks the voice chat for Summary, Decisions, Open questions, and Next steps.
4. Saved summary. The person stores that text on the topic. That history is what the next Continue prompt includes.

The person talks each topic through out loud with DeepDrive's built-in voice thinking partner. Summaries are saved automatically. The prompts are also available over the API for assistants and agents.

## What makes a good topic

A good topic is open-ended, personal, and decision-oriented. One sitting, about 10 to 20 minutes. The title is a question or a decision in the person's own words.

Good:

- Whether to take the role in another city
- The smallest offer I could charge for this month
- What I want the next year with my dad to look like

Bad:

- Weather (a lookup, not a conversation)
- Remember to buy milk (a task)
- General productivity (too vague to decide anything)
- Summarize this PDF (DeepDrive does not read files)

## Topic fields

- `title` (required, up to 300 characters)
- `why` (why it matters, up to 2000 characters)
- `category`: Personal (default), Business & side projects, Money, Home, Travel & planning, Health & habits, Relationships & family, Learning, Career, or another label up to 60 characters
- `tags`: optional short strings. Stored on the topic notes as `Tags: a, b`. There is no tags column.
- `rating`: integer 0 through 5. 0 means unrated. Set this only when the person states a preference.
- `status`: new, active, parked, or done. Default new.
- `minutes`: integer 1 through 240. Default 10.
- `opening_prompt`: optional. If omitted, DeepDrive writes one from the title and why.
- `notes`: optional.

## How to help your user

1. Interview briefly. Ask what is on their mind and which decisions are coming up (work, money, home, health, people, learning). Three to five questions, not a survey.
2. Draft 5 to 15 topics from their answers. Use their words. Do not invent topics they did not imply.
3. Show the list and wait until they confirm. Drop or edit anything they reject.
4. Then upload, or hand them a file.
   - Upload, when they created a token in Settings and pasted it to you: `POST https://deepdrive.app/api/topics/bulk` with `Authorization: Bearer dd_...` and a `deepdrive-topics` body, or call the MCP tool `create_topics_bulk` at `https://deepdrive.app/mcp`. Titles that already exist are skipped, not overwritten. At most 100 topics per call.
   - File, when they have not given a token: write JSON that matches https://deepdrive.app/schemas/import.json (example: https://deepdrive.app/examples/import.json). Tell them to import it under Settings. Do not ask them to paste a password.
5. Do not mint tokens, revoke tokens, import a full export, or delete the account. Those require the person signed in in the browser. A token cannot call `POST /api/import`.

## Start here

- [Guide for assistants](https://deepdrive.app/agents)
- [JSON Schema](https://deepdrive.app/schemas/import.json) and [example import](https://deepdrive.app/examples/import.json)
- [OpenAPI](https://deepdrive.app/api/openapi.json): machine-readable API, also at https://deepdrive.app/.well-known/openapi.json
- [Full guide](https://deepdrive.app/llms-full.txt): request examples for the main endpoints
- [Developers](https://deepdrive.app/developers): API tokens, MCP setup for Claude, Cursor, and ChatGPT
- [Plugin manifest](https://deepdrive.app/.well-known/ai-plugin.json)
- [MCP server card](https://deepdrive.app/.well-known/mcp.json): Streamable HTTP at https://deepdrive.app/mcp
- [Privacy](https://deepdrive.app/privacy) and [Terms](https://deepdrive.app/terms)

## About the product

- [Home](https://deepdrive.app/): what DeepDrive is, how it works, FAQ
- [AI brainstorming partner](https://deepdrive.app/ai-brainstorming-partner)
- [Talk through ideas with AI](https://deepdrive.app/talk-through-ideas-with-ai)
- [Voice journaling with AI](https://deepdrive.app/voice-journaling-ai)
- [Rubber duck AI](https://deepdrive.app/rubber-duck-ai)
- [Think out loud](https://deepdrive.app/think-out-loud)
- [Pricing](https://deepdrive.app/pricing): free 4,000 tokens, Starter, Pro, top-ups
- [DeepDrive vs ChatGPT voice](https://deepdrive.app/compare/chatgpt-voice)
- [About](https://deepdrive.app/about)

## Auth

Create a token in the signed-in Settings page. It is shown once. Send it on every request:

```
Base URL: https://deepdrive.app
Authorization: Bearer dd_your_token
MCP URL: https://deepdrive.app/mcp
```

Tokens can read and update that person's topics, including `POST /api/topics/bulk`. They cannot mint tokens, import a JSON file, or delete the account. Do not send topic text, summaries, or email addresses to analytics.

## Main endpoints

- `GET /api/topics?q=&status=&category=` list or search topics
- `POST /api/topics` create one topic
- `POST /api/topics/bulk` create up to 100 confirmed topics (API tokens allowed)
- `PATCH /api/topics/{id}` update a topic
- `POST /api/topics/{id}/ratings` set a rating from 0 to 5
- `POST /api/pick` rating-weighted random topic
- `GET /api/prompts/opening|continue|wrapup?topic=` copy-ready prompts
- `POST /api/topics/{id}/sessions` save a conversation summary
- `GET /api/library` the full curated library (with hook, tags, drive_length_minutes)
- `GET /api/library/starter` about eight diverse library topics
- `POST /api/library/add` copy several library topics by id
- `GET /api/recommendations?limit=&minutes=&surprise=` personalized library picks, each with a one-line reason
- `POST /api/recommendations/{library_id}/feedback` dismissed, not_interested, or more_like_this
- `GET /api/export` export topics, sessions, and ratings
- `POST /api/import` import a full export or a simple topic file (Firebase sign-in only)

## Examples

Base URL: https://deepdrive.app

List topics that are still in play:

```
GET /api/topics?status=active
Authorization: Bearer dd_your_token
```

Search by title:

```
GET /api/topics?q=sleep
Authorization: Bearer dd_your_token
```

Create one topic. `title` is required. `rating` is an integer 0-5. `status` is new, active, parked, or done.

```
POST /api/topics
Authorization: Bearer dd_your_token
Content-Type: application/json

{"title":"What good work looks like this quarter","category":"Career","why":"If I cannot describe it, the week fills with motion.","status":"new"}
```

Create several topics after the person confirms them. Duplicate titles are skipped.

```
POST /api/topics/bulk
Authorization: Bearer dd_your_token
Content-Type: application/json

{"format":"deepdrive-topics","topics":[{"title":"Whether to take the role in another city","why":"The offer is real, and the next month decides it.","category":"Career","tags":["decision"],"rating":4}]}
```

The same JSON file can be imported in Settings. Schema: https://deepdrive.app/schemas/import.json. Example: https://deepdrive.app/examples/import.json. That import route requires the person to be signed in. An API token uses the bulk route above instead.

Update a topic:

```
PATCH /api/topics/TOPIC_ID
Authorization: Bearer dd_your_token
Content-Type: application/json

{"status":"active","notes":"Talked about the one outcome that would make the quarter a success."}
```

Rate it. `0` clears the rating.

```
POST /api/topics/TOPIC_ID/ratings
Authorization: Bearer dd_your_token
Content-Type: application/json

{"rating":4}
```

Pick a topic. Higher ratings and active topics are more likely. A topic used today is less likely. Done topics are skipped unless `include_done` is true.

```
POST /api/pick
Authorization: Bearer dd_your_token
Content-Type: application/json

{"category":"Career"}
```

Prompts to paste into a voice chat. `kind` is opening, continue, or wrapup.

```
GET /api/prompts/opening?topic=TOPIC_ID
GET /api/prompts/continue?topic=TOPIC_ID
GET /api/prompts/wrapup?topic=TOPIC_ID
Authorization: Bearer dd_your_token
```

Save the summary after the drive. At least one text field is required. Do not invent a summary the person did not supply.

```
POST /api/topics/TOPIC_ID/sessions
Authorization: Bearer dd_your_token
Content-Type: application/json

{"summary":"The quarter succeeds if the proposal is sent.","decisions":"Send it Friday.","open_questions":"Who reviews it?","next_steps":"Draft the one-pager."}
```

Starter library and adding several curated topics:

```
GET /api/library/starter
Authorization: Bearer dd_your_token

POST /api/library/add
Authorization: Bearer dd_your_token
Content-Type: application/json

{"ids":["health-sleep","career-good-work"]}
```

Library topics have `id`, `category`, `title`, `why`, `opening_prompt`, and `added`. They also have `hook` (a short question to show the person), `tags` (lowercase labels), and `drive_length_minutes` (a rough drive length). Use the hook when you suggest a topic out loud, and the length to match the drive the person is about to take. These three fields are not copied onto the person's own topic when it is added.

Personalized recommendations, learned from this person's picks, ratings, and drives. Offer one or two with their `reason`; use `slot: "surprise"` picks sparingly; send `not_interested` when the person says no.

```
GET /api/recommendations?limit=5&minutes=20
Authorization: Bearer dd_your_token
```

```json
{"generated_at":"2026-11-03T16:00:00Z","recommendations":[{"id":"biz-first-customers","category":"Business & side projects","title":"Who the first ten customers are","why":"A named list of people beats another week of polishing the idea.","hook":"Could I name ten real people who would pay?","tags":["customers","sales","focus"],"drive_length_minutes":30,"slot":"fit","score":1.54,"reason":"You rate Business & side projects topics highly.","reason_code":"category_affinity"}]}
```

Add one the normal way (`POST /api/library/{id}/add` or `POST /api/library/add`). Tell DeepDrive no thanks, or more like this:

```
POST /api/recommendations/biz-first-customers/feedback
Authorization: Bearer dd_your_token
Content-Type: application/json

{"action":"not_interested"}
```

Export:

```
GET /api/export
Authorization: Bearer dd_your_token
```

## MCP

`POST https://deepdrive.app/mcp` with the same bearer token. JSON-RPC methods: `initialize`, `tools/list`, `tools/call`. Tools: list_topics, search_topics, get_topic, create_topic, create_topics_bulk, update_topic, rate_topic, pick_topic, get_prompt, save_session, list_sessions, export, recommend_topics, recommendation_feedback. `create_topics_bulk` is the tool for a confirmed list of 5 to 15 topics. `recommend_topics` returns the same personalized picks as `GET /api/recommendations`; present the reason and ask before adding. The server is stateless and does not use a session id.