Skip to main content

API Reference

Import the public API from req. Each page explains signatures, parameters, returned values, error conditions, and examples. Follow Getting Started for installation and native transport linking.

Choose an API for your task​

  • HTTP Functions — Send requests and start streams.
  • Client — Reuse connections, apply defaults, and prepare/send requests.
  • Request — Represent and validate an outgoing request.
  • Response — Inspect metadata, read bodies, handle status, and close streams.
  • Headers — Read, repeat, replace, and merge HTTP fields.
  • QueryParams — Manage repeated parameters and query/form encoding.
  • URL — Parse, inspect, transform, and resolve targets.
  • JSONValue — Construct, parse, mutate, and read typed JSON values.
  • Auth — Generate Basic/Bearer headers and control inheritance.
  • Timeout — Set independent connect/read/write deadlines.
  • CookieJar — Store scoped cookies and select or extract them.
  • HTTPError and ErrorKind — Understand individual error kinds and available context.
  • Bytes and encode_utf8 — Work with explicit byte-oriented content.

Read the examples​

Complete examples include import req and a raising def main(). Short call snippets assume req is imported and run inside a raising function. Signatures retain source types and defaults; mut self marks mutation of the owner. Underscore-prefixed modules are outside the application API.

Three core rules​

  1. Ordinary requests return buffered bodies; stream() returns after headers and requires a choice of whole-body or chunk consumption.
  2. HTTP 4xx/5xx returns normally; call raise_for_status() to require status success.
  3. Client and Response are movable owners. Manage closure through contexts and avoid implicit copies.