C3 AI Documentation Home

Building a Front End on C3 with React

A C3 front end is an ordinary static React single-page application (SPA) that calls the C3 Agentic AI Platform's typed backend over HTTP. The C3 Agentic AI Platform serves your built files and answers POST /api/8/{Type}/{action} requests, and the same application runs unchanged off it, so there is no separate "C3 React" to learn. The C3 Agentic AI Platform owns a fixed spine, which is the Type system, the /api/8 typed API, authentication, the design tokens, and the build-and-serve path. You own the React application on top of that spine: the components, pages, routing, state, and styling.

Most of what you know about React carries over unchanged, and only a specific set of concerns takes a C3 form, which is why this guide is small. The parts you spend the most time on, building components and pages, managing state, and routing, are plain React. What changes sits at the seam between your application and the C3 Agentic AI Platform spine: how the front end reaches the backend, how a request authenticates, how the application is configured and served, and how it adopts the C3 look. The C3 Front-End Architecture maps each part of the ordinary web-development workflow to its C3 form and explains why the difference exists, so read it first.

The guide follows the developer's path, from an empty package to a deployed application. Read it in order the first time, because each part builds on the one before it.

Get started

Getting a working application onto your machine is the first milestone, and it takes four steps. You learn the ownership boundary, connect the C3 AI VS Code extension to a single-node environment (SNE), create the package with a hand-written manifest and npm create vite, and run the front end locally. The step that catches people is the local dev loop: by default npm run dev serves the interface with no backend and no proxy, so the front end's api/8 calls return 404 at localhost. Real data appears after you deploy, or through the optional dev proxy that The Local Dev Loop covers.

Connect to the backend

Reaching the typed backend is the one thing every front end must do, so these two pages are the heart of the guide. Every interaction is a single POST /api/8/{Type}/{action} call, and the same signed session token that authenticates it travels several ways depending on where the front end runs. Read these before building features, because a request that is shaped or authenticated wrong is the most common reason a front end that renders locally still returns no data once deployed.

  • Make API Requests teaches the one call, the query language, the read-versus-write body shapes, and efficient querying at scale.
  • Authenticate Requests teaches how the call proves who you are and which transport to use for each deployment.

Style

Styling is the one part of building the interface that takes a C3-specific form; everything else in the user interface (UI) is plain React. You bind your component library to the C3 design tokens so the application reads as a genuine C3 product rather than a generic site.

Ship it

Shipping turns your source into static files and puts them on a running environment. You build the bundle and deploy it two ways. The C3 AI VS Code extension starts the application on a single-node environment, which you then open from Studio. Studio Release Management builds a versioned artifact and deploys it onto a shared environment. Set the one serving option that decides whether clean paths work.

  • Bundle and Serve builds the static bundle and serves it under the application path.
  • Deploy to an Environment starts the application on a single-node environment from the extension, and deploys a Built Artifact onto a shared environment through Studio.

The C3-specific must-knows

A handful of conventions are load-bearing, and an application that ignores them does not work. Keep these in mind as you read:

  • The API call is POST /api/8/{Type}/{action} with a relative URL, and the base comes from the c3AppUrlPrefix cookie. Hardcoding the cluster, environment, and application is the most common deployment break.
  • When C3 serves the application, the c3auth cookie authenticates every call, so you write no authentication code.
  • The build sets base: './' so assets resolve under the application path. By default the local dev server has no backend behind it, so api/8 calls return 404 until you deploy; adding a dev proxy to reach a running environment is an optional, development-only setup.
  • Serving the application at a clean root requires spaMode in the UiService configuration, because without it the bare URL redirects to the console.

What this guide does not teach

Keeping the guide to the C3-specific surface only works because the deferred topics are linked, not dropped. React itself, the component libraries, routing, state management, and writing tests belong to the React ecosystem and to each library's own documentation. Migrating an existing SDL application to React, and forking a specific base application, are per-application concerns documented with each application. Serving several applications under one base URL is a C3 Agentic AI Platform serving concern, documented with the UiService configuration.

The current state

Read this guide with three things in flux, because the C3 Agentic AI Platform is mid-transition. SDL is being retired in favor of React, so disregard SDL-era guidance that leads you to build on the deprecated framework. The recommended component toolkit is still being finalized, so treat the toolkit recommendation as a default rather than a settled standard. The sanctioned design-token package has not yet shipped, so styling currently means reproducing the token values by hand. Each page notes where its guidance depends on one of these.

Was this page helpful?