Getting started

Ingram Cloud runs an AI assistant for each of your end-users. You design one agent and Ingram Cloud runs one private clone of it, a smith, per person: their own memory, conversations, tools and connections. Your backend drives it over /v1; this console is where you watch it.

1. Pick your path

All of them drive the same run loop: a smith created by curl is the same smith your AI SDK app talks to.

2. Set your coding agent up first

If Claude Code, Cursor, Codex or another agent is writing this integration, point it at the docs first, so it uses the endpoint and field names that exist rather than the ones it would guess:

curl https://cloud.ingram.tech/llms.txt

That is the machine-readable index of these docs, every page linked to its raw Markdown twin, with the base URL, version header and OpenAPI URL at the top. Tell your agent to read it before writing Ingram Cloud code, and paste the instruction block from Coding agents into your AGENTS.md or CLAUDE.md. That page also covers giving the agent a scratch project whose token can't reach production, and the run and event feeds it debugs from.

3. Get a project and a token

Sign in, and the console puts you in an organization with one project. A project is a tenant: its own smiths, agents, tokens and usage, isolated from every other. Use one per environment — staging and production are separate projects, not a flag.

Mint a tenant-admin token at Settings → API keys. It is shown once and bound to that project inside the JWT. Keep it server-side. Full rules in Auth & tokens.

Runs need a verified card. Adding one costs nothing and credits €10 immediately (billing); until then runs are refused with 402 card_required. You are charged per token of inference plus stored bytes, with the first 1 GiB per organization free — no seat fee and no per-smith fee.

4. The three things to get right

One smith per end-user, not one smith per app. The smith is the unit of isolation: its memory, threads and connections belong to that person. Share one smith across your users and you have shared their memory. Create smiths keyed by your own user id (external_id), which makes creation idempotent, and design the behaviour once as an agent rather than repeating it per smith. Modeling your users covers signed-in, anonymous and mixed cases.

Tenant-admin tokens never reach a browser. Mint a short-lived smith token per session instead; it is bound to one smith and can touch nothing else, so it is safe in a page or a mobile app.

Pin IC-Api-Version: 2026-05-01 on every request. Omit it and each request gets the latest version, so a future release can change your app's behaviour without a deploy.

5. Watch it run

Every run has a detail page in the console with its transcript, the tools it called and a timed span waterfall with per-call cost. The same data is on the API: GET /v1/runs, the append-only event feed, and GET /v1/runs/{rid}/trace. Register a webhook when you want the events pushed instead of polled.

6. Before you go to production

• Set a budget with action: "block".
• Move token minting server-side, if it isn't already.
• Decide which tools need approval.
• Point your staging and production apps at separate projects.
• Subscribe to the events you care about, run.failed first.

Where to go next

• Core concepts — the five nouns everything else builds on.
• Quickstart — the three-curl path to a streamed reply.
• Coding agents — the full setup for AI-assisted work.
• Tools & approvals — let a smith call your code.
• Ecosystem — every surface, channel and integration.