# API Reference

URL: /docs/reference/api/
Section: reference
Tags: reference, api, exports

--------------------------------------------------------------------------------

Public API Everything you need is importable from chirp: from chirp import ( # Core App, AppConfig, # HTTP Request, Response, Redirect, # Template return types Template, InlineTemplate, Fragment, Page, Stream, ValidationError, OOB, # Real-time EventStream, SSEEvent, # Middleware types Middleware, Next, AnyResponse, # Context g, get_request, # Auth get_user, login, logout, login_required, requires, is_safe_url, # Forms form_from, form_or_errors, form_values, FormBindingError, # Errors ChirpError, ConfigurationError, HTTPError, MethodNotAllowed, NotFound, # Tools ToolCallEvent, ) Core App The application class. Mutable during setup, frozen at runtime. app = App(config=AppConfig(...)) Decorators: Decorator Description @app.route(path, methods=...) Register a route handler @app.error(code_or_type) Register an error handler @app.template_filter(name=...) Register a kida template filter @app.template_global(name=...) Register a kida template global @app.on_startup Register a startup callback @app.on_shutdown Register a shutdown callback @app.on_worker_startup Register a per-worker startup callback @app.on_worker_shutdown Register a per-worker shutdown callback @app.tool(name, description) Register an MCP tool Methods: Method Description app.add_middleware(mw) Add middleware to the pipeline app.run() Start the development server (freezes the app) app.check() Validate hypermedia contracts CLI The chirp command is registered as a console script: Command Description chirp new <name> Scaffold a new project chirp new <name> --minimal Scaffold a minimal project chirp run <app> Start the dev server (e.g. chirp run myapp:app) chirp check <app> Validate hypermedia contracts The <app> argument is an import string in module:attribute format. The attribute defaults to app when omitted (e.g. chirp run myapp resolves to myapp:app). AppConfig Frozen dataclass for application configuration. See Configuration. HTTP Request Frozen dataclass representing an incoming HTTP request. Properties: method, path, query, headers, cookies, content_type htmx Properties: is_fragment, htmx_target, htmx_trigger, is_history_restore Async Methods: body(), text(), json(), form(), stream() Response HTTP response with chainable .with_*() API. Methods: with_status(), with_header(), with_headers(), with_content_type(), with_cookie(), without_cookie(), with_hx_redirect(), with_hx_location(), with_hx_trigger(), with_hx_trigger_after_settle() Redirect Convenience for 302 redirects: Redirect(url). Template Return Types Type Description Template(name, **ctx) Full template render Template.inline(source, **ctx) Render from string (prototyping) InlineTemplate(source, **ctx) String-based template (returned by Template.inline()) Fragment(name, block, **ctx) Named block render Page(name, block, **ctx) Auto-detect fragment vs full page Stream(name, **ctx) Progressive streaming render ValidationError(name, block, **ctx) 422 fragment response OOB(main, *fragments) Out-of-band multi-fragment response Real-Time Type Description EventStream(generator) Server-Sent Event stream SSEEvent(data, event, id, retry) Structured SSE event Context Export Description g Request-scoped mutable namespace (ContextVar-backed) get_request() Get the current request from ContextVar Auth Export Description get_user() Get the current authenticated user (or AnonymousUser) login(user) Regenerate session and set the authenticated user logout() Regenerate session and clear the authenticated user @login_required Decorator: require authentication @requires(*permissions) Decorator: require specific permissions is_safe_url(url) Check whether a redirect URL is safe (relative, same origin) See Built-in Middleware for setup and usage. Forms Export Description form_from(request, datacls) Bind form data to a frozen dataclass. Raises FormBindingError on failure. form_or_errors(request, datacls, template, block, ...) Bind or return ValidationError. Returns T | ValidationError. form_values(form) Convert dataclass or mapping to dict[str, str] for template re-population. FormBindingError Raised when form binding fails. .errors is dict[str, list[str]]. Errors Error Description ChirpError Base exception for all Chirp errors ConfigurationError Invalid configuration (missing secret_key, etc.) HTTPError Base for HTTP errors NotFound 404 Not Found MethodNotAllowed 405 Method Not Allowed Next Steps Errors -- Error handling in detail Return Values -- Return type guide Configuration -- AppConfig options

--------------------------------------------------------------------------------

Metadata:
- Word Count: 524
- Reading Time: 3 minutes