Factories

A factory captures the constants every tool for one API shares — base URL, auth, casing, envelope — and returns a callable that turns a schema plus a URL template into a Tool. Defaults set on the factory can be overridden per tool.

`api_key_tool_factory`

Tools for an API that authenticates with static headers: x-api-key, a bearer token you already hold, several headers at once.

def api_key_tool_factory(
    base_url: BaseUrl,
    api_key_headers: Optional[ApiKeyHeaders] = None,
    *,
    pack: str,
    body_case: KeyCase = "camel",
    query_case: KeyCase = "snake",
    path_case: KeyCase = "snake",
    timeout: int = 20,
    quota_doc_url: Optional[str] = None,
    envelope: Optional[Envelope] = None,
    scope_refusals: Optional[Iterable[ScopeRefusal]] = None,
    pagination: Optional[Pagination] = None,
    body_format: BodyFormat = "json",
    query_format: QueryFormat = "repeat",
    static_query: Optional[Dict[str, Any]] = None,
    static_headers: Optional[Dict[str, str]] = None,
    on_call: Optional[CallSink] = None,
    credential_statuses: Optional[Iterable[int]] = None,
    follow_redirects: bool = False,
) -> ToolBuilder: ...

str | Callable[[], str]

required

Base URL for the API, e.g. "https://api.example.com/". A callable is resolved on every request.

Dict[str, str] | Callable[[], Dict[str, str]]

default:"None"

Headers injected on every request. May be omitted here and supplied per tool via api_key_headers_override; a tool with neither raises DeclarationError. An empty value in a literal mapping is rejected at build time — on the factory and on the tool.

"camel" | "snake" | "pascal" | "kebab"

default:"\"camel\""

Case convention for body keys.

"camel" | "snake" | "pascal" | "kebab"

default:"\"snake\""

Case convention for query keys.

"camel" | "snake" | "pascal" | "kebab"

default:"\"snake\""

Case convention for path keys.

int

default:"20"

Request timeout in seconds.

Optional[str]

default:"None"

Link to the API’s own rate-limit documentation. Carried onto every tool.

Optional[Envelope]

default:"None"

How this API reports failure inside a 200 response. Declared once here, enforced on every tool the factory builds.

Optional[Iterable[ScopeRefusal]]

default:"None"

How this API says a credential’s grant does not cover the call, so each such answer raises InsufficientScope naming the scopes to add. The standard WWW-Authenticate challenge needs no declaration. See ScopeRefusal.

Optional[Pagination]

default:"None"

Where this API keeps its cursor. Declare it per tool instead when only some endpoints are lists — a retrieve labelled with a cursor parameter it does not accept is worse than no declaration.

"json" | "form"

default:"\"json\""

"form" for form-encoded APIs such as Stripe and Twilio.

"repeat" | "bracket"

default:"\"repeat\""

"bracket" for APIs expecting expand[0]=x in the query string.

Optional[Dict[str, Any]]

default:"None"

Query parameters sent verbatim on every request.

Optional[Dict[str, str]]

default:"None"

Headers sent verbatim on every request — an Azure api-version, a Notion-Version.

Optional[CallSink]

default:"None"

Receives a ToolCall after every invocation of every tool this factory builds. Declared here because observability belongs to the deployment, not to one endpoint.

Optional[Iterable[int]]

default:"None"

Statuses that mean “your credential” rather than “not allowed”. Defaults to {401}.

bool

default:"False"

Whether a 3xx is followed. Off by default: on a JSON API a redirect is usually a wrong URL, and following it quietly hides that. Turn it on per tool with follow_redirects_override where the answer is a redirect — GitHub serves Actions logs as a 302 to a signed URL. The headers named in api_key_headers are dropped when a redirect leaves the origin.

ToolBuilder

A callable that builds Tool instances with these defaults. Its parameters are listed under the builder.

from charter import api_key_tool_factory

scraper = api_key_tool_factory(
    pack="scraper",
    base_url="https://api.example.com/",
    api_key_headers={"x-api-key": "key-123"},
)

`oauth_tool_factory`

Tools for an API that authenticates with a bearer token. The token is fetched from credential_provider on every call, so a provider that refreshes is picked up without rebuilding the tools. Charter never runs the OAuth flow itself: a missing, expired or rejected token raises CredentialError for the host application.

def oauth_tool_factory(
    base_url: BaseUrl,
    provider: str,
    credential_provider: CredentialProvider,
    scopes: Optional[ScopesDeclaration] = None,
    *,
    pack: str,
    body_case: KeyCase = "camel",
    query_case: KeyCase = "snake",
    path_case: KeyCase = "snake",
    timeout: int = 20,
    quota_doc_url: Optional[str] = None,
    envelope: Optional[Envelope] = None,
    scope_refusals: Optional[Iterable[ScopeRefusal]] = None,
    pagination: Optional[Pagination] = None,
    body_format: BodyFormat = "json",
    query_format: QueryFormat = "repeat",
    static_query: Optional[Dict[str, Any]] = None,
    static_headers: Optional[Dict[str, str]] = None,
    on_call: Optional[CallSink] = None,
    expiry_leeway_seconds: int = 10,
    credential_statuses: Optional[Iterable[int]] = None,
    follow_redirects: bool = False,
    token_header: Optional[str] = None,
) -> ToolBuilder: ...

The keyword parameters it shares with api_key_tool_factory — body_case, query_case, path_case, timeout, quota_doc_url, envelope, scope_refusals, pagination, body_format, query_format, static_query, static_headers, on_call, credential_statuses, follow_redirects — behave identically. The five that differ:

str

required

Provider identifier passed to get_credentials, e.g. "google". Also the peer.service label on every record.

CredentialProvider

required

Supplies the bearer token. See Credentials.

Optional[ScopesDeclaration]

default:"None"

What these tools need from a grant: scope strings, or AnyOf(...) where the provider accepts several, narrowest first. A mapping of Kind to lists declares them for each kind of credential the provider issues. Carried as metadata for scopes_for, consent screens and approval UIs; Charter does not request them. A tool’s scopes_override list replaces the default kind’s and keeps the others; a mapping replaces the kinds it names.

int

default:"10"

How dead a token must be before the runtime refuses to send it. A guard against sending something already expired, not a refresh policy.

Optional[str]

default:"None"

The header the token goes in, for an API that does not read it from Authorization. None sends Authorization: Bearer <token>; a name sends the token bare in that header — "X-Shopify-Access-Token" for Shopify. Only where the token lands changes: it still comes from credential_provider on every call, so a provider that renews keeps renewing, which a key in api_key_headers cannot. Dropped on a redirect that leaves the origin, and masked in the debug log, as Authorization is.

from charter import oauth_tool_factory
from charter.auth import StaticTokenProvider

gmail = oauth_tool_factory(
    pack="mygmail",
    base_url="https://gmail.googleapis.com/",
    provider="google",
    credential_provider=StaticTokenProvider("test-token"),
    scopes=["https://www.googleapis.com/auth/gmail.modify"],
)

The builder

Both factories return a callable with the same parameters, except that api_key_headers_override exists only on the API-key builder and scopes_override only on the OAuth one.

def create_tool(
    name: str,
    args_schema: Type[BaseModel],
    method: HTTPMethod,
    url_template: Union[str, Sequence[str]],
    description: Optional[str] = None,
    action_label: Optional[str] = None,
    body_case_override: Optional[KeyCase] = None,
    query_case_override: Optional[KeyCase] = None,
    path_case_override: Optional[KeyCase] = None,
    timeout_override: Optional[int] = None,
    mode: Optional[str] = None,
    response_handler: Optional[ResponseHandler] = None,
    build_request: Optional[Callable[[BaseModel], TransportOverride]] = None,
    quota_cost: Optional[int] = None,
    envelope_override: Optional[Envelope] = None,
    pagination_override: Optional[Pagination] = None,
    body_format_override: Optional[BodyFormat] = None,
    static_body: Optional[Dict[str, Any]] = None,
    on_call_override: Optional[CallSink] = None,
    follow_redirects_override: Optional[bool] = None,
) -> Tool: ...

Parameter	Purpose
`name`	Tool name
`args_schema`	The schema — the contract
`method`	`GET` / `POST` / `PATCH` / `PUT` / `DELETE`
`url_template`	Path relative to the base URL, with a placeholder per `Path()` field — or several, most specific first, for one operation served at more than one path (routes)
`description`	What the tool does, for the model
`action_label`	Short user-facing phrase, for approval UIs
`mode`	Which `Mode`-marked fields survive into the LLM schema
`response_handler`	Async callable that reshapes the payload
`build_request`	Escape hatch returning a `TransportOverride`
`quota_cost`	What one call costs against the provider’s rate limit
`static_body`	Constant body keys for this endpoint — the GraphQL document
`*_override`	The factory default, replaced for this endpoint

Two details of how overrides resolve:

body_case_override, query_case_override, path_case_override, timeout_override, envelope_override, pagination_override, on_call_override, follow_redirects_override, api_key_headers_override and scopes_override replace the factory value when they are not None. Passing None keeps the factory’s.
body_format_override is applied with or, so "json" and "form" both work but a falsy value falls back to the factory’s.

static_body is per tool rather than per factory because the constant belongs to the operation: every Linear tool POSTs to the same graphql URL, and the query document is what distinguishes one from another.

from typing import Annotated

from pydantic import BaseModel
from charter import Path, api_key_tool_factory


class TranscriptRequest(BaseModel):
    video_id: Annotated[str, Path()]


api = api_key_tool_factory(
    pack="acme",
    base_url="https://api.example.com/",
    api_key_headers={"x-api-key": "default-key"},
)

fetch_transcript = api(
    name="fetch_transcript",
    args_schema=TranscriptRequest,
    method="GET",
    url_template="transcript/{video_id}",
    description="Fetch the transcript of a video.",
)

admin_transcript = api(
    name="fetch_transcript_admin",
    args_schema=TranscriptRequest,
    method="GET",
    url_template="admin/transcript/{video_id}",
    description="Fetch a transcript with the privileged key.",
    api_key_headers_override={"x-api-key": "admin-key"},
    timeout_override=60,
)

Errors

Condition	Result
An empty header value, on the factory or a tool	`DeclarationError` at build time
No headers on either the factory or the tool	`DeclarationError` naming the tool
A non-async `response_handler`	`DeclarationError` at build time
`401` from the API	`CredentialError`
Any other status `>= 400`	`APIError` carrying the status and a body excerpt

api_key_tool_factory — the narrative version, with more auth shapes
Authorization servers — what to pass as credential_provider
Packs — factories already declared against eleven APIs

Core

Schema

Authentication

Runtime

Operating

`api_key_tool_factory`

`oauth_tool_factory`

The builder

Errors

​api_key_tool_factory

​oauth_tool_factory

​The builder

​Errors

​Related

`api_key_tool_factory`

`oauth_tool_factory`

The builder

Errors

Related