City SDK

Federation and SDK capabilities for many AI products.

Downcity's City SDK is the way AI builders create, deploy, and call City. A Federation can serve multiple web apps, extensions, desktop tools, client demos, and internal tools without making each product rebuild the same AI backend.

City exposes a stable product-facing service boundary instead of a raw provider API. Inside City, capabilities are organized as Service, Action, and AIService.

  • the product client holds city_id + user_token
  • it calls text(), stream(), image(), and other services through User City
  • City keeps the model catalog, provider routing, hooks, usage, and env behind the boundary

The server-side runtime class is Federation (also called the Federation here); product clients use the City client to reach it. For the boundary between them, see Federation and City.

Pick your reading path

Start HereI want to run one full call chain

Deploy a Federation, expose one model, issue a token, and make a product client call text() or stream() successfully.

Mental ModelI want to understand the boundaries first

Separate the Federation, product clients, your business backend, AI gateways, and real providers before implementation details start leaking together.

Real ScenariosI am connecting a real city now

Read the practical guides for pure-client products, multi-product reuse, auth, provider env, hooks, and business logic.

PackagesI want to read by package

Jump straight into @downcity/city, client, and CLI docs; official service packages live in Federation Services Docs.

APII only need the interfaces

Jump straight to City, User City, Admin City, HTTP API, and environment variables.

One diagram for the full model

Many product clientsWeb apps, extensions, apps, desktop tools, client demos, and internal tools.User City + city_id + user_token
FederationVerifies the token, resolves the model catalog, and dispatches the request to AIService, services, or custom Service actions.
Hooks and usageQuota, balance, billing, logging, and risk control can plug into the Federation while your own business rules stay in your system.
Upstream executionOpenAI, Claude, Gemini, private models, or your own AI Gateway / proxy.

Product clients see stable Service actions and model IDs. Which provider or gateway City uses internally remains a server-side detail.

What the City SDK owns

  • runtime database and Service-owned tables
  • provider keys and runtime env
  • user_token verification and admin_secret_key management
  • model metadata and handlers through Provider.model() + AIService.use()
  • public model catalogs through client.ai.listModels()
  • usage records and hook extension points

What it does not own

  • your user system
  • orders, subscriptions, CRM, or content data
  • product-specific pages, interaction, and business UX
  • a public “unified provider API” for arbitrary third-party systems

More precisely:

The City SDK owns the Federation and its Service-facing AI infrastructure. Your products still own their users, business logic, interface, and pricing model.

  1. First integration: start at Quickstart
  2. Want the full city model: read Concepts
  3. Connecting a real business scenario: read Guides
  4. Want a package-by-package map: read Packages
  5. Need concrete interfaces: come back to Reference

Understand City

Build the Federation mental model before connecting real products.

Table of Contents

Pick your reading pathOne diagram for the full modelWhat the City SDK ownsWhat it does not ownRecommended order