# Ingram Cloud > Hosted AI agents over one REST API. You design a versioned **agent** (`/v1/agents`) and run one isolated clone — a **smith** (`/v1/smiths`) — for each of your end-users. Every run is on the record: each model call, tool, approval, and dollar, traced end to end. - **Base URL**: `https://api.cloud.ingram.tech` — every endpoint lives under `https://api.cloud.ingram.tech/v1`. This is the only base URL; ignore any other host. - **Version header**: send `IC-Api-Version: 2026-05-01` on every request. - **Auth**: `Authorization: Bearer `. - **OpenAPI spec (source of truth)**: https://api.cloud.ingram.tech/openapi.json — generated from the live API; trust it over any prose for exact paths and shapes. - **OpenAI-compatible**: `POST /v1/chat/completions` works with the OpenAI SDKs — point `baseURL` at `https://api.cloud.ingram.tech/v1` and use a smith token as the key. Every page below is also raw Markdown: take its URL and it already ends in `.md`, or request any `/docs/` page with `Accept: text/markdown`. ## Start here - [Quickstart](https://cloud.ingram.tech/docs/quickstart.md): Go from a fresh Ingram Cloud project to a streamed agent reply in three curl commands — create an agent, spin up a smith, and run it over the API. - [Core concepts](https://cloud.ingram.tech/docs/concepts.md): Learn the core nouns behind Ingram Cloud — project, agent, smith, thread, and run — and why an agent is the design while a smith is one running clone per end-user. - [Auth & tokens](https://cloud.ingram.tech/docs/auth.md): How to authenticate the Ingram Cloud API: tenant-admin vs smith tokens, the scopes each carries, RS256 JWT identity, and how to mint and rotate them. ## Guides - [Modeling your users](https://cloud.ingram.tech/docs/modeling-users.md): Map your users onto smiths and threads before you write code — the design decision that makes per-user isolation, billing, and history fall out for free. - [Where tools run](https://cloud.ingram.tech/docs/tool-execution.md): A mental model for where a smith's tools actually run — hosted, self-hosted over MCP, or inline — and what happens machine by machine across web, chat, and email. - [Build a support agent](https://cloud.ingram.tech/docs/support-agent.md): A worked example: build a support agent embedded on your site that serves both signed-in and logged-out visitors while keeping each person's conversation isolated. ## Build - [Agents](https://cloud.ingram.tech/docs/agents.md): Design an agent once — instructions, model, tools, auto-memory — and run it across thousands of smiths by reference. Publish versions, roll out, pin, and override. - [Smiths](https://cloud.ingram.tech/docs/smiths.md): A smith is one end-user's running clone of an agent — the unit of data isolation, with its own memory, threads, and connections. Create one per person over the API. - [Runs & streaming](https://cloud.ingram.tech/docs/runs.md): A run is one turn of a smith: input messages in, streamed events while it works, an output record at the end. Learn run lifecycle, streaming, pausing, and resuming. - [Tools & approvals](https://cloud.ingram.tech/docs/tools.md): Give a smith tools to call: hosted tools that Ingram Cloud runs in-process and MCP tools your own server executes, optionally gated behind human approval. - [Sandbox: a filesystem and a shell](https://cloud.ingram.tech/docs/sandbox.md): Give an agent a disposable Linux box for the duration of a run — a writable /workspace, a shell, network access, and secrets you control. - [Memory](https://cloud.ingram.tech/docs/memory.md): Each smith keeps an automatic memory — a working-memory doc plus semantic recall over its own past messages — per-user isolated, inspectable and editable from the API and console. - [Files & vector stores](https://cloud.ingram.tech/docs/retrieval.md): Upload documents, index them into searchable vector stores, and give agents a knowledge base with the file_search tool. - [Embeddings](https://cloud.ingram.tech/docs/embeddings.md): Turn text into vectors on your OpenAI key — an OpenAI-compatible endpoint for building your own search or clustering. - [Models](https://cloud.ingram.tech/docs/models.md): The models an agent or smith can run on, the providers behind them, and how to bring your own key. List the live catalog with GET /v1/tenant/models. ## Ecosystem - [Ecosystem & compatibility](https://cloud.ingram.tech/docs/ecosystem.md): The map of how Ingram Cloud connects to the world — the API surfaces and SDKs you drive a smith from, the channels it reaches your users on, the models and tools it uses, and the ways it plugs into other systems. Standards-first throughout. - [OpenAI-compatible API](https://cloud.ingram.tech/docs/openai-compat.md): Drive a smith over the OpenAI Chat Completions wire format — point the OpenAI SDK or Vercel AI SDK at Ingram Cloud and stream replies with no custom transport to learn. - [Conversations](https://cloud.ingram.tech/docs/conversations.md): A conversation is a listable, titled handle on a thread of runs — create one, run inside it over the OpenAI Responses API, list its transcript, and rename or delete it. Held independently of smith memory. - [Vercel AI SDK](https://cloud.ingram.tech/docs/ai-sdk.md): Use @ingram-cloud/ai-sdk to drive a smith from the Vercel AI SDK — a pre-configured provider plus helpers for smith identity, server-side memory, and approvals. - [Flue](https://cloud.ingram.tech/docs/flue.md): Use @ingram-cloud/flue to drive a smith from a Flue agent — register a smith as a model provider, attach Ingram-hosted tools over MCP, and resolve approvals, all over standard surfaces. - [eve](https://cloud.ingram.tech/docs/eve.md): Use @ingram-cloud/eve to wire a smith into a Vercel eve agent — run a smith as the agent's model, attach Ingram-hosted tools as an MCP connection, and resolve approvals, all over standard surfaces. - [Deployments & schedules](https://cloud.ingram.tech/docs/deployments.md): Deploy a smith or agent to Slack, Telegram, WhatsApp, email, an MCP server, or a private hosted web page so inbound messages run it automatically and replies return to the same conversation — plus cron schedules. - [Connectors](https://cloud.ingram.tech/docs/connectors.md): Add a deployed agent to Claude or ChatGPT as a connector: OAuth 2.1 discovery on the MCP endpoint, connect tokens, and per-user isolation intact. - [MCP Apps](https://cloud.ingram.tech/docs/mcp-apps.md): Attach an interactive HTML UI to an agent and serve it from a kind:mcp deployment, so a supporting host (Claude, ChatGPT) renders it inline — the standard MCP Apps extension (SEP-1865), degrading to text where it can't render. - [Pulumi provider](https://cloud.ingram.tech/docs/pulumi.md): Declare your tenant's Ingram Cloud configuration — agents, MCP servers, integrations, webhooks, model keys — as Pulumi resources with @ingram-cloud/pulumi, so a change is a pulumi up. ## Operate - [Events & webhooks](https://cloud.ingram.tech/docs/events.md): Notable actions in a project land on one append-only event feed — run lifecycle, tool calls, approvals, connections, budget alerts. Poll it or register signed webhooks for the same envelope. - [Usage, cost & budgets](https://cloud.ingram.tech/docs/usage.md): Track what a project consumes — tokens, runs, and cost — and cap it with budgets. A project's tenant-scope budget also caps how much it draws from the org's credit wallet. - [Customers & metering](https://cloud.ingram.tech/docs/metering.md): Meter what your customers' smiths consume so you can bill them — Ingram Cloud tracks quantities and your cost while what you charge stays in your own billing stack. - [Credits & billing](https://cloud.ingram.tech/docs/billing.md): Prepaid credits cover your organization's platform usage with Ingram Cloud — top up by card via Stripe, check your balance, and review the credit ledger. ## Reference - [TypeScript SDK](https://cloud.ingram.tech/docs/sdk.md): @ingram-cloud/sdk is the API wire contract in TypeScript — Zod request/response schemas, SSE and webhook event types, JSON response types — plus a typed management-plane client built on it. - [API at a glance](https://cloud.ingram.tech/docs/api.md): Conventions for the Ingram Cloud API — base URL, required headers, the OpenAI-standard error envelope, id prefixes, and the full endpoint map, backed by the OpenAPI spec.