Skip to content
Jadwigo docs

Searches the question bank: a need in, ranked questions out.

POST
/api/v1/question-searches
curl --request POST \
  --url https://app.jadwigo.pl/api/v1/question-searches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "words": "example", "words_en": "example", "skills": [ "example" ], "mistakes": [ "example" ], "can_do": "example", "contexts": [ "example" ], "curriculum_tags": [ "example" ], "resemble": "example", "language": "pl", "grade": "example", "limit": 1 }'

Called with the bank’s shared read token, not a Supabase token.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

A search need, from jadwigo-bank schemas/need.schema.json at commit 703b679. It carries at least one of words, skills, can_do or resemble.

object
words

The need in plain words, in the caller’s language

string
words_en

English terms for the keyword arm when the need is not in English; never stored on a page

string
skills
Array<string>
mistakes
Array<string>
can_do
string
contexts
Array<string>
curriculum_tags

E.g. pl-2017:II.3.3, ccss:3.OA.C.7

Array<string>
resemble

A task to resemble, e.g. a homework problem’s text

string
language
required
string
Allowed values: pl en uk
grade
required

Canonical form: the bare number, e.g. “3”

string
limit
integer
>= 1 <= 9007199254740991

Responses

Section titled “Responses”

200

Section titled “200”

OK.

Media typeapplication/json

A bank search’s answer, version 1, from jadwigo-bank schemas/search-envelope.schema.json at commit 703b679.

object
version
required
number
Allowed value: 1
need

A search need, from jadwigo-bank schemas/need.schema.json at commit 703b679. It carries at least one of words, skills, can_do or resemble.

object
words

The need in plain words, in the caller’s language

string
words_en

English terms for the keyword arm when the need is not in English; never stored on a page

string
skills
Array<string>
mistakes
Array<string>
can_do
string
contexts
Array<string>
curriculum_tags

E.g. pl-2017:II.3.3, ccss:3.OA.C.7

Array<string>
resemble

A task to resemble, e.g. a homework problem’s text

string
language
required
string
Allowed values: pl en uk
grade
required

Canonical form: the bare number, e.g. “3”

string
limit
integer
>= 1 <= 9007199254740991
arm

The arm that answered (A, A1, B, B1, C, C2)

string
stage
string
Allowed values: first final
timing_ms

Server-side stage times in milliseconds

object
embed
number
vectors
number
rows
number
keyword
number
rerank
number
total
number
cache
string
Allowed values: hit miss off
bank_rev

Sha256 of the index manifest the service answered from; the publisher writes it with the rows, so a caller can tell which build of the bank a row came from

string
rows
required
Array<object>
object
id
required
string
/^set_/
rank
required
integer
>= 1 <= 9007199254740991
score
required
number
arm
required
string
vector_score
number | null
bm25_score
number | null
rerank_score
number | null
best_view

The index view the vector hit came from: title, samples, meaning_pl, meaning_en, needs

string | null
view_scores
object
key
additional properties
number
grade
string | null
titles
required

By language code: pl, en

object
key
additional properties
string
languages
Array<string>
skill_ids
Array<string>
curriculum_tags
Array<string>
problem_types
Array<string>
question_types
Array<string>
views
Array<string>
source

Where the set’s questions come from: khan, own, ai

string
credit

The attribution line the product must show: Khan Academy, CC BY-NC-SA 4.0 and the exercise’s URL

string
enrichment

The set’s enrichment fields the caller may show, each the set page’s value: summary and can_do by language, mistake_classes as records, contexts as word lists by language; any other key, a private body among them, is dropped on parse

object
summary

By language code: pl, en

object
key
additional properties
string
can_do

By language code: pl, en

object
key
additional properties
string
mistake_classes
Array<object>
object
id
required
string
pl
required
string
en
required
string
spot
required

How the mistake shows in one answer

string
contexts

By language code: pl, en

object
key
additional properties
Array<string>
content_hash

Sha256 of the set page the row was built from

string
media

Shas of the pictures the set’s questions need

Array<string>
items

How many questions the set holds (the bank’s field name)

integer
>= -9007199254740991 <= 9007199254740991
body

A private body never crosses this route

private_body

A private body never crosses this route

state
required

One row per known arm: the asked arm’s outcome and not_asked for the rest

Array<object>
object
arm
required
string
state
required
string
Allowed values: ok empty abstained degraded not_asked
detail

What degraded it (an embedder or reranker failure), never a key or a URL with a token

string

Example 

{
  "version": 1,
  "need": {
    "language": "pl"
  },
  "stage": "first",
  "cache": "hit",
  "state": [
    {
      "state": "ok"
    }
  ]
}

401

Section titled “401”

An error: {error: {type, message}}. The type names the cause, and answers with one status:

  • 400: BadRequest, ServerFieldSupplied
  • 401: NotSignedIn, Unauthorized
  • 404: NotFound
  • 409: AccountMissing, AttemptClaimed, AttemptPreview, AssignmentClosed, AttemptFinished, AttemptNotFinished, AttemptPaused, QuestionNotOpen, TryOutOfOrder, AnswerConflict, EventIdMismatch, WriteOnce
  • 429: AnswerLimit
  • 502: BankUnavailable
Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: BadRequest ServerFieldSupplied NotSignedIn NotFound AccountMissing AttemptClaimed AttemptPreview AssignmentClosed AttemptFinished AttemptNotFinished AttemptPaused QuestionNotOpen TryOutOfOrder AnswerConflict EventIdMismatch WriteOnce AnswerLimit Unauthorized BankUnavailable
message
required
string

Example 

{
  "error": {
    "type": "BadRequest"
  }
}

4XX

Section titled “4XX”

An error: {error: {type, message}}. The type names the cause, and answers with one status:

  • 400: BadRequest, ServerFieldSupplied
  • 401: NotSignedIn, Unauthorized
  • 404: NotFound
  • 409: AccountMissing, AttemptClaimed, AttemptPreview, AssignmentClosed, AttemptFinished, AttemptNotFinished, AttemptPaused, QuestionNotOpen, TryOutOfOrder, AnswerConflict, EventIdMismatch, WriteOnce
  • 429: AnswerLimit
  • 502: BankUnavailable
Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: BadRequest ServerFieldSupplied NotSignedIn NotFound AccountMissing AttemptClaimed AttemptPreview AssignmentClosed AttemptFinished AttemptNotFinished AttemptPaused QuestionNotOpen TryOutOfOrder AnswerConflict EventIdMismatch WriteOnce AnswerLimit Unauthorized BankUnavailable
message
required
string

Example 

{
  "error": {
    "type": "BadRequest"
  }
}

5XX

Section titled “5XX”

An error: {error: {type, message}}. The type names the cause, and answers with one status:

  • 400: BadRequest, ServerFieldSupplied
  • 401: NotSignedIn, Unauthorized
  • 404: NotFound
  • 409: AccountMissing, AttemptClaimed, AttemptPreview, AssignmentClosed, AttemptFinished, AttemptNotFinished, AttemptPaused, QuestionNotOpen, TryOutOfOrder, AnswerConflict, EventIdMismatch, WriteOnce
  • 429: AnswerLimit
  • 502: BankUnavailable
Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: BadRequest ServerFieldSupplied NotSignedIn NotFound AccountMissing AttemptClaimed AttemptPreview AssignmentClosed AttemptFinished AttemptNotFinished AttemptPaused QuestionNotOpen TryOutOfOrder AnswerConflict EventIdMismatch WriteOnce AnswerLimit Unauthorized BankUnavailable
message
required
string

Example 

{
  "error": {
    "type": "BadRequest"
  }
}