feat(content-provider): supports search cards and access card details by id #20175

sanjaysargam · 2026-01-20T09:07:12Z

Purpose / Description

Expand CardContentProvider to return card IDs and cardinfo details

Fixes

Fixes Expand CardContentProvider to return card IDs and cardinfo details #20112

Approach

I copy-pasted the proposed solution by @joaquintoral. And understood how it works on external app like AnkiConnectAndroid and test it properly.

How Has This Been Tested?

Run AnkiConnectAndroid locally - https://github.com/sanjaysargam/AnkiconnectAndroid/tree/card
Run AnkiDroid.

FindCards - /cards

curl -X POST http://192.168.0.101:8765 \
  -H "Content-Type: application/json" \
  -d '{
    "action": "findCards",
    "version": 6,
    "params": {
      "query": "deck:current"
    }
  }'

response in logcat:

2026-01-20 13:50:07.435  3211-8481  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  received json:
{"action":"findCards","version":6,"params":{"query":"deck:current"}}

2026-01-20 13:50:07.437  3211-8481  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  Processing findCards with query: deck:current

2026-01-20 13:50:07.437  3211-8481  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  findCards query: deck:current

2026-01-20 13:50:07.484  3211-8481  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  findCards found 1 cards for query: deck:current

2026-01-20 13:50:07.486  3211-8481  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  response json:
{"result":[1768897186292],"error":null}

FindCardByID - /cards/#

curl -X POST http://192.168.0.101:8765 \
  -H "Content-Type: application/json" \
  -d '{
    "action": "cardsInfo",
    "version": 6,
    "params": {
      "notes": [1768897186292]
    }
  }'

response in logcat:

2026-01-20 13:59:09.410  3211-9024  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  received json:
{"action":"cardsInfo","version":6,"params":{"notes":[1768897186292]}}

2026-01-20 13:59:09.412  3211-9024  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  Processing cardsInfo for IDs: [1768897186292]

2026-01-20 13:59:09.413  3211-9024  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  cardsInfo requested for card IDs: [1768897186292]

2026-01-20 13:59:09.425  3211-9024  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  Processed card ID: 1768897186292

2026-01-20 13:59:09.425  3211-9024  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  cardsInfo returning 1 card(s)

2026-01-20 13:59:09.428  3211-9024  AnkiConnectAndroid  com.kamwithk.ankiconnectandroid  D  response json:
{"result":[{"id":1768897186292,"noteId":1768897186292,"deckId":0,"templateIndex":0,"question":"Card 1768897186292 question","answer":"Card 1768897186292 answer","flags":0,"tags":[]}],"error":null}

Learning (optional, can help others)

This was completely new for me. I haven’t worked on scenarios where an external app consumes our APIs before, so exploring this is really interesting

Checklist

Please, go through these checks before submitting the PR.

You have a descriptive commit message with a short title (first line, max 50 chars).
You have commented your code, particularly in hard-to-understand areas
You have performed a self-review of your own code
UI changes: include screenshots of all affected screens (in particular showing any new or changed strings)
UI Changes: You have tested your change using the Google Accessibility Scanner

david-allison

The ContentProvider needs heavy testing as it's our public API

Please add tests for all additional functionality

I'd strongly suggest splitting this PR into two parts:

Adding the public /cards/ endpoints: easy
Adding additional properties to /cards: harder

Specifically for (2), I would like to see the source/docs of upstream Anki Desktop AnkiConnect, and how the data is modelled there. This is how people are used to consuming our data.

AnkiDroid/src/main/java/com/ichi2/anki/provider/CardContentProvider.kt

david-allison · 2026-01-20T10:29:35Z

api/src/main/java/com/ichi2/anki/FlashCardsContract.kt

+        /**
+         * Due date for this card (day for review, timestamp for learning).
+         */
+        public const val DUE: String = "due"


This is a bad abstraction in the database, we probably want to expose something more useable publicly

david-allison · 2026-01-20T10:29:49Z

api/src/main/java/com/ichi2/anki/FlashCardsContract.kt

+        /**
+         * Interval in days since last review.
+         */
+        public const val INTERVAL: String = "interval"


ditto: this is optional

david-allison · 2026-01-20T10:30:14Z

api/src/main/java/com/ichi2/anki/FlashCardsContract.kt

+        public const val INTERVAL: String = "interval"
+
+        /**
+         * Ease factor (0-2500, divide by 1000 for actual ease).


An output of 2500 is confusing

No explanation of what this does under FSRS

david-allison · 2026-01-20T10:31:58Z

AnkiDroid/src/main/java/com/ichi2/anki/provider/CardContentProvider.kt

+                val cardIds = col.findCards(query)
+
+                // Fast path: Only if _id is requested
+                val onlyRequestingId = columns.size == 1 && columns[0] == FlashCardsContract.Card._ID


.singleOrNull

david-allison · 2026-01-20T10:32:41Z

AnkiDroid/src/main/java/com/ichi2/anki/provider/CardContentProvider.kt

+                // Search for cards using Anki browser syntax
+                val columns = projection ?: FlashCardsContract.Card.DEFAULT_PROJECTION
+                val query = selection ?: ""
+                val cardIds = col.findCards(query)


This can throw on bad syntax: and throws (I believe).

Ensure we throw consistent exceptions from the API, and that exceptions are appropriately tested and documented

returns empty list on a bad query

This isn't documented in the tests.

I also don't think it's correct, looking at the implementation of findCards

If it is correct, it doesn't appear to be consistent with our other endpoints.

Regardless

add a test, with a search of and

update the KDoc on findCards

sanjaysargam · 2026-01-20T18:29:46Z

The ContentProvider needs heavy testing as it's our public API

For this, separate PR would be better

david-allison · 2026-01-20T22:10:49Z

Not sure how to read the comment, but just to confirm:

Content Provider PRs need to include tests. It's not okay to submit them later

david-allison · 2026-01-22T20:21:36Z

Two PRs

… by id

david-allison

Thanks! Much easier to get through.

The returned columns aren't asserted on

david-allison · 2026-01-23T11:03:37Z

AnkiDroid/src/main/java/com/ichi2/anki/provider/CardContentProvider.kt

+                // Search for cards using Anki browser syntax
+                val columns = projection ?: FlashCardsContract.Card.DEFAULT_PROJECTION
+                val query = selection ?: ""
+                val cardIds = col.findCards(query)


This isn't documented in the tests.

I also don't think it's correct, looking at the implementation of findCards

If it is correct, it doesn't appear to be consistent with our other endpoints.

Regardless

add a test, with a search of and

update the KDoc on findCards

david-allison · 2026-01-23T11:05:34Z

AnkiDroid/src/androidTest/java/com/ichi2/anki/tests/ContentProviderTest.kt

+                "999999999",
+            )
+
+        assertThrows<BackendNotFoundException> {


This is asserted in other places

We'll probably want to document it, and tighten this down later. RuntimeException was previously asserted

david-allison · 2026-01-23T11:07:33Z

AnkiDroid/src/androidTest/java/com/ichi2/anki/tests/ContentProviderTest.kt

    }

+    @Test
+    fun testSearchCards_returnsMatchingCards() {


the intention of this test is unclear:

Are you adding a note with one, or two cards?

The test would pass with both, you might want to disambiguate this into two tests

david-allison · 2026-01-23T11:09:17Z

api/src/main/java/com/ichi2/anki/FlashCardsContract.kt


+        /**
+         * The content:// style URI for cards. Can be used to search for cards or access specific cards.
+         * For examples on how to use the URI for queries see class description.


consider linking the class description

david-allison · 2026-01-23T11:09:39Z

api/src/main/java/com/ichi2/anki/FlashCardsContract.kt

     */
    public object Card {
+        /**
+         * This is the ID of the card in the Anki database.


Suggested change

* This is the ID of the card in the Anki database.

* The ID of the card in the Anki database.

david-allison · 2026-01-23T11:10:30Z

AnkiDroid/src/main/java/com/ichi2/anki/provider/CardContentProvider.kt

+                val cardId = uri.pathSegments[1].toLong()
+                val columns = projection ?: FlashCardsContract.Card.DEFAULT_PROJECTION
+                val rv = MatrixCursor(columns, 1)
+                val card = col.getCard(cardId)


Update the documentation on getCard: @throws

david-allison · 2026-01-23T11:12:07Z

AnkiDroid/src/main/java/com/ichi2/anki/provider/CardContentProvider.kt

+        private const val CARDS = 1100
+        private const val CARD_ID = 1101


Why are you reusing the 1 prefix?

github-actions bot added the Needs Review label Jan 20, 2026

david-allison requested changes Jan 20, 2026

View reviewed changes

lukstbit added Needs Author Reply Waiting for a reply from the original author and removed Needs Review labels Jan 20, 2026

This comment was marked as resolved.

Sign in to view

sanjaysargam force-pushed the content branch from 6a53841 to 2b5cf90 Compare January 23, 2026 09:07

feat(content-provider): supports search cards and access card details…

9148f6d

… by id

sanjaysargam force-pushed the content branch from 2b5cf90 to 9148f6d Compare January 23, 2026 09:14

sanjaysargam requested a review from david-allison January 23, 2026 09:14

sanjaysargam added Needs Review and removed Needs Author Reply Waiting for a reply from the original author labels Jan 23, 2026

david-allison requested changes Jan 23, 2026

View reviewed changes

	* This is the ID of the card in the Anki database.
	* The ID of the card in the Anki database.

		private const val CARDS = 1100
		private const val CARD_ID = 1101

Uh oh!

feat(content-provider): supports search cards and access card details by id #20175

Are you sure you want to change the base?

feat(content-provider): supports search cards and access card details by id #20175

Conversation

sanjaysargam commented Jan 20, 2026

Purpose / Description

Fixes

Approach

How Has This Been Tested?

Learning (optional, can help others)

Checklist

Uh oh!

david-allison left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

david-allison Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sanjaysargam commented Jan 20, 2026

Uh oh!

david-allison commented Jan 20, 2026

Uh oh!

This comment was marked as resolved.

david-allison commented Jan 22, 2026

Uh oh!

david-allison left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

david-allison Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

david-allison Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

david-allison Jan 20, 2026 •

edited

Loading

david-allison Jan 23, 2026 •

edited

Loading

david-allison Jan 23, 2026 •

edited

Loading