API Reference

List Courses

Get all courses available to your organization. Use the course id from this response in search requests.

GET /api/v1/partner/courses

Headers: x-api-key: tq_pk_your_key

Response:

{
  "success": true,
  "courses": [
    {
      "id": "068038d2-507d-43b9-955f-8d591ae8be75",
      "name": "Textbook Of Ophthalmology",
      "code": "OPH-101",
      "materials_count": 1
    }
  ],
  "total_courses": 1
}

Field	Type	Description
`id`	string	Course ID — use this in search requests
`name`	string	Course name
`code`	string	Course code (if set)
`materials_count`	integer	Number of processed materials available

Only courses with at least one processed material are shown.

Search Course Materials

Search within a specific course using natural language.

POST /api/v1/partner/search

Headers

Header	Required	Description
`x-api-key`	Yes	Your partner API key
`Content-Type`	Yes	`application/json`

Request Body

{
  "query": "What is the anatomy of the retina?",
  "course_id": "068038d2-507d-43b9-955f-8d591ae8be75",
  "top_k": 5
}

Field	Type	Required	Default	Description
`query`	string	Yes	—	Search query (1-1000 characters)
`course_id`	string	Yes	—	Course ID to search within
`top_k`	integer	No	5	Number of results to return (1-20)

Response

{
  "success": true,
  "results": [
    {
      "title": "Anatomy of the Eye - Retinal Layers",
      "content": "The retina is a thin layer of neural tissue that lines the back of the eye...",
      "key_terms": ["retina", "photoreceptors", "rods", "cones", "macula"],
      "images": [
        "Cross-section diagram showing the 10 layers of the retina"
      ]
    }
  ],
  "total_results": 3,
  "query": "What is the anatomy of the retina?"
}

Result Fields

Field	Type	Description
`title`	string	Section or topic title
`content`	string	Relevant passage from course material (up to 3000 characters)
`key_terms`	string[]	Key concepts in this passage
`images`	string[]	Descriptions of diagrams/figures in this section (if any)

How Search Works

TutorQ uses dual-embedding semantic search:

Your query is converted to an embedding vector
We search across all course materials using weighted scoring:
- 70% content similarity (full text match)
- 30% title/key-terms similarity (concept match)
Results are ranked by combined similarity score
Context windowing adds surrounding content (±1 chunk) for full context

This means students can ask questions in natural language — they don't need to know exact terms from the textbook.

Examples

Basic Search

curl -X POST https://api.tutorq.ai/api/v1/partner/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: tq_pk_your_key" \
  -d '{
    "query": "treatment for glaucoma",
    "course_id": "your-course-id"
  }'

Narrow Search (High Precision)

curl -X POST https://api.tutorq.ai/api/v1/partner/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: tq_pk_your_key" \
  -d '{
    "query": "intraocular pressure measurement techniques",
    "course_id": "your-course-id",
    "top_k": 2,
    "similarity_threshold": 0.7
  }'

Broad Search (More Results)

curl -X POST https://api.tutorq.ai/api/v1/partner/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: tq_pk_your_key" \
  -d '{
    "query": "eye diseases overview",
    "course_id": "your-course-id",
    "top_k": 10,
    "similarity_threshold": 0.4
  }'

Error Responses

Status	Body	Meaning
`401`	`{"detail": "Invalid API key"}`	Authentication failed
`403`	`{"detail": "Course does not belong to your organization"}`	Course not in your tenant
`404`	`{"detail": "Course not found"}`	Course ID doesn't exist
`429`	`{"detail": "Rate limit exceeded"}`	Too many requests
`500`	`{"detail": "Internal search error"}`	Server error (retry)

Rate Limits

Default: 100 requests per minute per API key. Contact us if you need higher limits.

Authentication Usage & Billing