Set up the AI backend

Connect interpret through your existing API client to an interpretation endpoint: an application server route that accepts the assistant request and returns a supported result. The endpoint can use your chosen model provider. Keep provider credentials on the server. Start with the client adapter and request/response contract if you have not connected the browser yet.

Start with the reference service in scripted mode to check the connection, then configure a model for natural-language requests. Scripted mode recognizes predefined requests; it does not interpret arbitrary questions.

What your endpoint receives and returns

In the quick-start example, your interpret(request, { signal }) adapter sends a JSON POST through your application’s API client. The body is an AiViewRequest: the prompt, disclosed field metadata, current filter/sort view, locale, timezone, reference instant and any explicitly enabled context. Forward signal through your client so a cancelled assistant request can abort the HTTP request. You can use your existing route conventions; /api/ai-view/interpret is the reference service’s route.

Your server must return a successful HTTP response with a supported assistant result as its JSON body. For example, an allowed Amount sort can return:

{
  "kind": "command",
  "sort": {
    "mode": "replace",
    "items": [{ "field": "amount", "direction": "desc" }]
  }
}

The browser validates this result against its configured fields and capabilities before executing it. Other supported results include registered actions, answers, clarification questions and unsupported feedback. A raw provider response or an arbitrary text string is not this contract.

Use createAiViewResponseSchema(fields, descriptors) from @revolist/revogrid-pro to generate the structured-output JSON Schema for your approved fields and action descriptors. The reference backend demonstrates the provider integration and response validation. Your server must authenticate users and enforce its own policy; browser-supplied metadata does not grant access.

Your API client should reject failed HTTP requests, and your interpret adapter should let that rejection reach the assistant. If the route is missing, check your server routing or development proxy before troubleshooting the model. The optional Fetch helper rejects non-success responses with the HTTP status.

Authentication at each connection

The user’s prompt and authentication travel together in the HTTP request, in different places: the prompt and permitted context are JSON in the body, while the user’s session cookie or application access token identifies the caller.

Connection	Credential	Who validates it?
Browser → your application’s interpretation route	Existing user session cookie or user bearer access token	Your application authenticates the user and checks their permissions.
Your application → separate reference AI service, if used	Private AI_ACCESS_TOKEN, sent by the server-side host proxy as a bearer token	The reference service checks this service credential. The proxy supplies the user ID derived from your authenticated session.
Your backend → model provider	Server-held provider credentials	The provider authenticates your backend’s provider account.

Only the first connection uses your browser API client. Reuse its existing cookie or bearer authentication and token-refresh handling; your interpret adapter only needs to forward the request and return the parsed assistant result. See client authentication.

The optional createAiHostProxy is server-side code. Its getUserId(request) callback must resolve your authenticated user. It rejects requests without a user, constructs the private service Authorization header itself, and supplies the trusted user ID rather than forwarding a browser-selected identity. Keep the service token and provider credentials out of browser configuration.

If your application route calls the model provider directly, the separate reference-service connection is unnecessary. Your route still owns user authentication, authorization and provider credentials.

Calling an API on another origin

Configure cross-origin authentication in your existing API client. For cookie-based requests, it must opt into credentials, your API must allow the exact application origin and credentialed requests through CORS, and your cookie settings must permit the request. For bearer authentication, allow the Authorization header through CORS.

If you choose the optional HTTP helper, its default Fetch behavior does not opt into cross-origin cookies. Supply a custom fetch for that case:

const interpret = createAiViewHttpInterpreter(
  'https://api.your-app.example/ai/interpret',
  {
    fetch: (input, init) => fetch(input, { ...init, credentials: 'include' }),
  },
);

The helper’s headers and custom fetch options configure transport; they do not implement authentication or token refresh.

Run and deploy the reference backend

The reference backend README includes exact local setup, environment templates, tests and the small authenticated host proxy. Leave both provider values empty for deterministic scripted mode, or set both OPENAI_API_KEY and AI_MODEL on the server for live mode. A partial configuration fails at startup.

1. Prepare the example workspace

These commands run from the root of a RevoGrid Pro repository checkout, using its declared Node and pnpm versions. They are for running the reference example; an application consuming the published package does not need to build this workspace.

pnpm install --frozen-lockfile
pnpm --filter @revolist/ui build:public
pnpm build:pro
cp examples/components/src/components/ai-assistant/backend/.env.example examples/components/src/components/ai-assistant/backend/.env.local

2. Start in scripted mode

Keep the provider values empty in the copied .env.local, then start the service:

pnpm --filter @revolist/ai-backend-example dev

In another terminal, start the demo host:

pnpm --filter @revolist/revogrid-demos dev

Open the local demo and type a request or choose a suggestion. All four frameworks try the service through the same-origin Vite proxy without a URL flag. If the backend is unavailable, free-form requests show a clear message and scripted suggestions still work.

Check backend status. It reports the configured mode, model and capabilities. A successful status response confirms the service is running; it does not validate provider credentials with a live request.

3. Connect a model

Set both OPENAI_API_KEY and AI_MODEL in the backend’s .env.local and restart the service. Use a model supported by your configured provider adapter. Submit a request in your own words and verify the resulting operation. Keep these values out of browser configuration.

For your own application, expose an authenticated /api/ai-view/interpret route, then call it through your existing API client as shown in the quick start. The reference service uses an orders fixture policy; replace it with server-approved fields and permissions for your data.

4. Prepare a remote deployment

For a remote deployment, keep the service on loopback behind your application’s HTTPS route. Enable AI_REMOTE, allow exact HTTPS origins, and keep its private bearer token in the server-only createAiHostProxy. Derive user identity from the application’s authenticated session, never a browser-supplied header. Origin checks supplement authentication.

Understand request limits

Defaults are five requests/minute/user, 20/UTC-day/user, 200/day overall, two concurrent calls, 1,024 generated tokens/call and a 30-second timeout. Reservations count failed calls and persist before model execution. Follow-up answers consume a second reservation. Storage failure blocks requests, and throttling returns HTTP 429 with Retry-After. This file-backed reference supports one process with persistent storage; replicas require a shared atomic quota owner. These controls bound requests/output, not an exact currency budget.

The rows fixture endpoint is a separate remote-data example, not a production business-data service. Production authorization and provider policy remain application responsibilities.

Next: Test your integration.