Querying

query()

Send a message to the runtime API and receive a governed response.

const result = await client.query(input: QueryInput): Promise<QueryResult>;

QueryInput

Property	Type	Required	Description
`botId`	`string`	Yes	The agent ID to query
`input`	`string`	Yes	The user's message
`conversationId`	`string`	No	Conversation ID for multi-turn chats

QueryOutput

A successful response contains:

Property	Type	Description
`conversationId`	`string`	Conversation ID — pass this back for follow-up queries
`response`	`string`	The AI-generated response
`intentDetected`	`string \| undefined`	The intent classified by the runtime, if any
`metadata`	`ResponseMetadata`	Governance and enforcement metadata

ResponseMetadata

Property	Type	Description
`capabilityAllowed`	`boolean`	Whether the intent was allowed by the Capability Profile
`enforcementReason`	`EnforcementReason \| undefined`	Why the request was restricted
`schemaEnforced`	`boolean`	Whether output schema enforcement was applied
`schemaFallbackUsed`	`boolean`	Whether a fallback response was used due to schema failure
`schemaValidationError`	`string \| undefined`	Schema validation error details

EnforcementReason

Value	Meaning
`'DENY_LIST'`	Intent is on the Capability Profile deny list
`'NOT_IN_ALLOW_LIST'`	Intent is not on the Capability Profile allow list
`'no_intent_match'`	No intent could be classified from the input
`'schema_fallback'`	Response didn't match the output schema; fallback used

Multi-turn Conversations

The conversationId returned in the first response should be passed back in subsequent queries to maintain conversation context:

// First message
const first = await client.query({
  botId: 'bot-123',
  input: 'What plans do you offer?',
});

if (!first.ok) return;

// Follow-up in the same conversation
const second = await client.query({
  botId: 'bot-123',
  input: 'What does the Growth plan include?',
  conversationId: first.data.conversationId,
});

Full Example

import { IlanaClient } from '@ilana/sdk';

const client = new IlanaClient({
  runtimeUrl: 'https://api.getilana.ai',
  token: 'your-embed-token',
});

const result = await client.query({
  botId: 'bot-123',
  input: 'How do I set up SSO?',
});

if (result.ok) {
  console.log('Response:', result.data.response);
  console.log('Intent:', result.data.intentDetected);
  console.log('Allowed:', result.data.metadata.capabilityAllowed);
} else {
  console.error(`[${result.error.code}] ${result.error.message}`);
}