Skip to content

deep search: update documentation of supported query parameters #1402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stefanhengl merged 1 commit into from
Nov 4, 2025
Merged

deep search: update documentation of supported query parameters #1402

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion docs/deep-search/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,9 +191,11 @@ Available query parameters:

- `filter_id` - Filter by conversation ID
- `filter_user_id` - Filter by user ID
- `filter_read_token` - Access conversations via read token (requires sharing to be enabled)
- `filter_is_starred` - Filter by starred conversations (`true` or `false`)
- `page_first` - Number of results per page
- `page_after` - Pagination cursor
- `sort` - Sort order: `created_at`, `-created_at`, `updated_at`, `-updated_at`
- `sort` - Sort order: `id`, `-id`, `created_at`, `-created_at`, `updated_at`, `-updated_at` (default: `-updated_at`)

## Managing conversations

Expand Down Expand Up @@ -225,6 +227,21 @@ curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140/questions/163
-H 'X-Requested-With: my-client 1.0.0'
```

## Accessing conversations via read tokens
Copy link
Member Author

@stefanhengl stefanhengl Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could omit this section, because we already document the query parameter in a previous section. However, it might be worth emphasizing this point because it connects the Web UI with the API.

Copy link
Contributor

@janhartman janhartman Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this section is really important and we should probably double down on how this is an alternative to the numeric IDs we never show to the user...
cc @mmanela

Copy link
Member Author

@stefanhengl stefanhengl Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In our API, the questions have numeric IDs and refer to their conversations, which also have integer IDs. If we want to switch to UUIDs, we should switch questions, too. Supporting both, ID and UUID is of course possible, but I don't think it's necessary and it is quite messy in the code and in the documentation.

Using UUID as IDs can also hurt db performance and it doesn't provide an intrinsic order either, which implies other API changes; for example, we have to remove support for id as sort parameter.

I am not against UUID. After all Amp uses them too. I just want to point out that they are often not for free.

If we want to switch to UUIDs for everything I think we should introduce a v2. This gives us the chance to remove ids completely and provide a clean API.

However I don't think that this user request really warrants a new API version. It's quite a specific request and we support it already ;-)

Alternative:

Switch to IDs for everything, which implies adding a flag to the DB that the thread has been shared. The only reason that we have UUIDs in the first place is because all threads are public once a customer enables sharing.

Con: Customers have already created UUID links, so we have to support UUIDs for a while.

Copy link
Contributor

@janhartman janhartman Nov 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your argument makes sense, I underestimated the complexity here. I agree that this is a specific ask and it's OK if we don't push this further


You can retrieve a conversation using its read token with the `filter_read_token` query parameter.

Each conversation includes a `read_token` field that allows accessing the conversation.
The read token is also visible in the web client URL and in the `share_url` field.
Note that you can only access other users' conversations via read tokens if sharing is enabled on your Sourcegraph instance.

```bash
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1?filter_read_token=5d9aa113-c511-4687-8b71-dbc2dd733c03' \
-H 'Accept: application/json' \
-H "Authorization: token $SRC_ACCESS_TOKEN" \
-H 'X-Requested-With: my-client 1.0.0'
```

## Response structure

**Conversation object:**
Expand Down