Skip to main content

​
Overview

The /api/get-context endpoint accepts any Kaggle competition URL and returns the token-optimized context. This is a convenience wrapper around GET /api/competitions/{slug} that automatically extracts the competition slug from the URL. Endpoint: POST /api/get-context Authentication: Not required (uses public Kaggle API)
For private competitions or to use your own Kaggle credentials, use POST /api/get-context-upload instead.

​
Request

​
url
string
required
Full Kaggle competition URL (e.g., https://www.kaggle.com/competitions/titanic)
​
top_n
integer
default:3
Number of top notebooks to include (1-10). Default: 3
​
stream
boolean
default:false
Enable streaming response (experimental). Default: false
​
ignore_patterns
array
List of patterns to ignore in notebook content (optional)

​
Response

Returns a CompetitionResponse object with the same structure as GET /api/competitions/.
​
slug
string
Competition slug extracted from the URL
​
title
string
Competition title
​
description
string
Competition description
​
metadata
object
Competition metadata including prize, team count, evaluation metric
​
status
string
Processing status: completed, processing, or failed
​
message
string
Status message (for processing/failed states)
​
cached_at
datetime
Timestamp when data was cached (ISO 8601 format)
​
toon_content
string
TOON-formatted competition context (only present when status is completed)

​
Examples

​
cURL

curl -X POST http://localhost:8000/api/get-context \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.kaggle.com/competitions/titanic",
    "top_n": 5
  }'

​
Python

import requests

response = requests.post(
    "http://localhost:8000/api/get-context",
    json={
        "url": "https://www.kaggle.com/competitions/house-prices-advanced-regression-techniques",
        "top_n": 3
    }
)

data = response.json()
if data["status"] == "completed":
    print(data["toon_content"])
else:
    print(f"Status: {data['status']} - {data.get('message')}")

​
JavaScript

const response = await fetch('http://localhost:8000/api/get-context', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://www.kaggle.com/competitions/digit-recognizer',
    top_n: 5
  })
});

const data = await response.json();
console.log(data.status, data.message || data.toon_content);

​
Implementation details

This endpoint:
  1. Extracts the competition slug from the provided URL using KaggleService._extract_slug()
  2. Delegates to get_competition_metadata() from the competitions router
  3. Returns the same response format as GET /api/competitions/{slug}
The URL parsing supports multiple Kaggle URL formats:
  • https://www.kaggle.com/competitions/titanic
  • https://kaggle.com/c/titanic
  • www.kaggle.com/competitions/titanic

​
Status flow

1

Cache miss

If the competition is not cached, you’ll receive a processing status. The server starts fetching data in the background.
2

Wait and retry

Wait 30-60 seconds and make the same request again.
3

Get results

Once processing completes, the status will be completed and toon_content will be populated.

​
Error responses

​
400
error
Invalid URL format or missing required fields
{
  "detail": "Invalid competition slug"
}
​
500
error
Server error during processing
{
  "detail": "Failed to fetch competition data"
}

Get competition by slug

Direct access using competition slug

Upload Kaggle credentials

Fetch private competitions with your own credentials

Build docs developers (and LLMs) love

Get started for freeTalk to us