kaggle

README

kaggle-go

An unofficial, minimal Go client for the Kaggle API, ported from Kaggle's official Python kagglesdk (the Connect-style JSON-RPC API at api.kaggle.com). It implements the subset needed to upload datasets, push GPU/TPU kernels, poll their status, and download their output — entirely in Go, with no Python or CLI dependency.

Not affiliated with or endorsed by Kaggle. "Kaggle" is a trademark of its owner.

Auth

Set KAGGLE_API_TOKEN to a Kaggle access token (the KGAT_… token created in your Kaggle account API settings). The client sends it as Authorization: Bearer <token>.

Usage

import (
    "danny.vn/kaggle"
    "danny.vn/kaggle/kernels"
    "danny.vn/kaggle/datasets"
)

c, _ := kaggle.New() // reads KAGGLE_API_TOKEN

// Upload data, push a GPU kernel, wait, fetch results:
d := datasets.New(c)
_ = d.CreateOrVersion(ctx, "owner", "my-data", "My data", []string{"chunks.jsonl"}, true, "")

k := kernels.New(c)
_, _ = k.Push(ctx, &kernels.ApiSaveKernelRequest{
    Slug: "owner/my-job", NewTitle: "my-job", Text: src,
    Language: "python", KernelType: "script", IsPrivate: true,
    EnableGpu: true, MachineShape: "NvidiaTeslaT4",
    DatasetDataSources: []string{"owner/my-data"},
})
st, _ := k.Status(ctx, "owner", "my-job")        // RUNNING → COMPLETE
paths, _ := k.Output(ctx, "owner", "my-job", "./out")

Supported subset

• kernels: SaveKernel (push), GetKernelSessionStatus, ListKernelSessionOutput, output download
• datasets: UploadDatasetFile, CreateDataset, CreateDatasetVersion, GetDatasetStatus

The surface is intentionally small — the subset required to run batch GPU jobs end to end. Each RPC has been validated against the live Kaggle API.

License

Apache-2.0. Ported from Kaggle's kaggle-api / kagglesdk (Apache-2.0); see NOTICE.

Documentation

Overview

Package kaggle is a minimal, unofficial Go port of the official Python kagglesdk Connect client. It speaks the same JSON-RPC protocol (POST {endpoint}/v1/{service}/{method}) against api.kaggle.com using a KGAT bearer token, and exposes the kernels and datasets subsets needed to upload data, push GPU kernels, poll status, and download outputs.

Not affiliated with or endorsed by Kaggle.

Index

• Constants
• type APIError
  • func (e *APIError) Error() string
• type Client
  • func New(opts ...Option) (*Client, error)
  • func (c *Client) Call(ctx context.Context, service, method string, req, out any) error
  • func (c *Client) CallRaw(ctx context.Context, service, method string, req any) (*http.Response, error)
  • func (c *Client) HTTPClient() *http.Client
  • func (c *Client) Token() string
  • func (c *Client) WhoAmI(ctx context.Context) (string, error)
• type IntrospectResult
• type Option
  • func WithEndpoint(e string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithToken(t string) Option
  • func WithUserAgent(ua string) Option
  • func WithVerbose(v bool) Option

Constants

const (
	// EndpointProd is the production Kaggle API endpoint (kagglesdk PROD).
	EndpointProd = "https://api.kaggle.com"
)

Types

type APIError

type APIError struct {
	Code    int
	Status  int
	Message string
}

APIError is a Kaggle API error. Code is the application-level error code from the JSON body (0 if absent); Status is the HTTP status code.

func (*APIError) Error

func (e *APIError) Error() string

Error formats the API error, preferring the application-level Code when set and otherwise falling back to the HTTP Status.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a minimal port of the Python kagglesdk Connect client. It POSTs JSON RPCs to {endpoint}/v1/{service}/{method} with Bearer (KGAT) auth.

The service subpackages (kernels, datasets) call through Call/CallRaw, so a single *Client is shared across them.

func New

func New(opts ...Option) (*Client, error)

New builds a Client. The token resolves from WithToken or, if empty, the KAGGLE_API_TOKEN environment variable (mirroring kagglesdk).

func (*Client) Call

func (c *Client) Call(ctx context.Context, service, method string, req, out any) error

Call POSTs req as JSON to service/method and decodes the JSON response into out. out may be nil for RPCs with no return body; req may be nil (sends {}). It mirrors kagglesdk error handling: a JSON body with code>=400 is an error.

func (*Client) CallRaw

func (c *Client) CallRaw(ctx context.Context, service, method string, req any) (*http.Response, error)

CallRaw POSTs req as JSON and returns the raw HTTP response. The caller owns resp.Body. Use this for streaming/download RPCs; prefer Call for JSON RPCs.

func (*Client) HTTPClient

func (c *Client) HTTPClient() *http.Client

HTTPClient returns the underlying HTTP client (for upload/download helpers).

func (*Client) Token

func (c *Client) Token() string

Token returns the bearer token (helpers PUT to signed upload URLs with it).

func (*Client) WhoAmI

func (c *Client) WhoAmI(ctx context.Context) (string, error)

WhoAmI introspects the client's token (security.OAuthService/IntrospectToken) and returns the authenticated Kaggle username. This lets callers avoid configuring a username — the access token self-identifies.

type IntrospectResult

type IntrospectResult struct {
	Active   bool   `json:"active,omitempty"`
	Username string `json:"username,omitempty"`
	UserID   int64  `json:"userId,omitempty"`
}

IntrospectResult is the subset of IntrospectToken we use: whether the token is active and the username that authorized it.

type Option

type Option func(*Client)

Option configures a Client.

func WithEndpoint

func WithEndpoint(e string) Option

WithEndpoint overrides the API endpoint (default EndpointProd).

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets the underlying HTTP client (e.g. to set a timeout).

func WithToken

func WithToken(t string) Option

WithToken sets the KGAT bearer token explicitly (otherwise KAGGLE_API_TOKEN).

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent overrides the User-Agent header.

func WithVerbose

func WithVerbose(v bool) Option

WithVerbose logs each request line to stderr.