Genaya

API Reference
SupportkeyGet API key
Intelligence

Genaya AI

Ask plain-language questions about your own data.

POST/ai/ask

Ask Genaya AI about your data

Asks a plain-language question about the organization's own records and returns a written answer. Requires scope: ai:read. The model never writes queries directly. It calls a fixed set of read-only tools and Genaya executes them, always scoped to the organization behind the API key - so a question can never reach another tenant's data. What it can see is derived from the key's own read scopes, and is limited to record types the key could already read through the REST endpoints. Asking the AI can never surface data that a direct GET with the same key would refuse. A key with no read scopes at all is rejected. Each answer is 10 Genaya AI credits (a question), exactly like a question in the app's chat: from the organization's included credits, then the prepaid balance at 1 cent a credit on the plans that keep going (Pro and Business; Individual after an owner turns it on). A failed answer spends none. When the credits are spent the API answers 403 permission_error with code insufficient_balance; a trial whose member has not verified their email answers code email_unverified; a pool that could not be read answers 503 service_unavailable with Retry-After. The request weight (10) on the API request meter is separate. `tier` is accepted and ignored - one engine answers every plan.

Request body

FieldTypeDescription
questionrequired
string
A plain-language question about the organization's records.
tier
string
Deprecated and ignored since 2026-09-10: one engine answers every plan. Accepted so integrations written against the earlier picker keep working; any value is treated as omitted.

Response 200

FieldTypeDescription
object
string
question
string
answer
string
The plain-language answer, with any internal formatting markers removed.
blocks
array of object
Structured output the model chose to emit alongside the prose - stat cards, tables or charts. Empty when the answer is plain text.
tier
string
Always `auto` - one engine answers every plan. Kept for compatibility.
model
string
nullable
credits
integer
The Genaya AI credits this answer spent from the organization's included credits (ten - a question, exactly like the app's chat). A failed answer spends none.
collectionsQueried
array of string
Which record types the model actually queried. An empty array means the answer was produced without looking anything up.
toolCallsUsed
integer
How many data lookups the model performed (capped per question).

Errors

400Malformed or missing parameters
401Bad, missing, or revoked key
402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up
403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off
429Rate limited
500Unexpected server error
503A counter the request depends on could not be read - retry after Retry-After