MyJackfruit

Help
Browse topics · More from code, and code examples

More from code, and code examples

← Back to Can I make an app that uses AI itself?

How do I use the AI chat API?

Short answer

Choose an agent from the platform's list, send the conversation as the signed-in person, with their own Grok token, and read the reply.

Before you start

A signed-in person's token and the key it is bound to, and that person's own Grok access token.

Words used here (4)
agent
An agent is your AI following one written procedure, its standing instructions, for one kind of work.
Jackfruit
Jackfruit is the vault agent: it finds, reads, writes and links records in your vaults, and makes new vaults for you.
Kai-Zen
Kai-Zen is the planning agent: it finds out what you want, chooses the way, hands the work to other agents and reports back.
field
A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
Steps
  1. Choose an agent from the platform's list.

    Fetch the list, with no token, and take the name of an entry whose pick is true:
    GET https://id.gilb.com/base/ai/agents

    More about this

    An agent is your AI following one written procedure, its standing instructions, for one kind of work. On 2026-11-11 the list held four picks: Jackfruit, Kai-Zen, Agent.Concept and Agent.Coder. The other entries are agents those hand work to; a name that is not a pick loads no standing instructions. The person's own agents are at GET https://id.gilb.com/base/ai/agents/mine, with their token; send such an agent's address as agentEntry instead of agent. With no agent named, the chat is Jackfruit.

  2. Send the conversation as the signed-in person.

    Send the messages as JSON, with the person's token and a new DPoP proof:
    POST https://id.gilb.com/base/ai/chat

    More about this

    The body holds messages, up to 32, each with role user or assistant and content of at most 24,000 characters, the last one from the user; agent, the name; and person_subscription with provider grok and access_token, the person's own Grok access token. Without it the answer is 403 ConnectYourOwnAI, Connect your own AI first — press Connect. Your AI works only for you., unless the platform owner has turned on a shared AI. contentVaultIds may name up to 32 vaults to work in. A field the body does not know answers 400. The agent's tools act as the signed-in person: it reads and writes only what that person may.

  3. Read the reply and its standing headers.

    The answer holds role, content, model and payer; the header x-standing-outcome says loaded when the agent's standing instructions were loaded.

    More about this

    x-standing-group names their group, and x-standing-reason says why when they were not loaded. Ask with Accept: text/event-stream to get the turn as events instead, ending in a message event. A failure at the AI provider answers 502.

Deeper

Also asked:

How does my app talk to the agents (AI chat API)? Choose an agent from GET https://id.gilb.com/base/ai/agents, then send the conversation to POST https://id.gilb.com/base/ai/chat as the signed-in person, with their own Grok access token.

Can my app offer an agent to its own users? Partly: each user signs in and needs their own Grok, and the agent works with that user's own access. The chat is built for GilbApp's own chat; a page on another origin reaches it only after the platform owner approves that origin for your app.

No chapter of the Developer Guide covers the AI chat yet; this answer is from the code at revision 498d29a0. The person's Grok access token comes from POST https://id.gilb.com/base/ai/subscription/connect with provider grok, which answers a code the person approves at xAI, then POST https://id.gilb.com/base/ai/subscription/poll with provider and device_code, repeated until it answers the token. The chat is built for GilbApp's own chat; a web page on another origin reaches it only after the platform owner approves that origin for your app. Claude Code reaches the same agents through its connector, as the answer on which agents there are shows.

An agent can also be given a handle to act inside a person's session, on part of what the person holds. Only a page on one of GilbPlatform's own sites, in the person's live browser session, can make one: POST https://id.gilb.com/base/delegation/session-grant with root, the address of a record, so the handle covers it and every record that is part of it; mode, read or write, read if left out; and ttlSeconds, one hour if left out, eight hours at most. A handle never reaches more than the person holds; asking for more answers 403. GET .../session-granted lists the live handles, and POST .../revoke with handle, or all true, ends them. The agent sends Authorization: SessionDelegate followed by the handle: GET .../whoami shows what it covers, and POST .../revoke-self drops it. A handle ends at sign-out, when the session ends, on revoke and when the platform restarts; it is not a sign-in token and cannot start a new session.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/routes/ai-chat.ts:1-17 (first-party SPA chat; DPoP-mandatory; person-held SuperGrok token; 403 ConnectYourOwnAI unless AI_SHARED_FOR_ALL_USERS=on; SSE when asked), :76 (MAX_TURNS 32), :81 (MAX_CONTENT 24000), :85-139 (body schema: messages, person_subscription, contentVaultIds maxItems 32, agent, agentEntry; additionalProperties false), :203-243 (payer; 403 text Connect your own AI first — press Connect. Your AI works only for you.), :284-296 (x-standing-outcome, -group, -text-sent, -reason, -groups-seen), :440-466 (requirePrincipal; The last message must be from the user. 400), :684-689 (JSON path headers), :711-716 (502 ChatUpstreamError); src/ai/complete-chat.ts:294-296 (reply: role, content, model, payer); src/ai/xai-oauth.ts:50-55 (provider grok or supergrok); src/routes/ai-subscription.ts:20-35 (bodies: provider; provider and device_code), :65-83 (POST /base/ai/subscription/connect, requirePrincipal, 200 with the device authorization), :85-112 (POST /base/ai/subscription/poll: 202 while pending, 200 with the tokens); src/ai/xai-oauth.ts:78-82, :142-185 (device_code, user_code, verification_uri: the person types the code at xAI), :193-209 (the poll):; src/ai/chat-agents.ts:39 (default Jackfruit), :56-57 (not-a-pick reason), :113-149 (only a pick loads); src/routes/ai-agents.ts:21-58 (GET /base/ai/agents; /mine with DPoP); src/ai/agent-list.ts:24-27, :102 (pick); src/ai/standing-instructions.ts:1076-1090 (outcomes loaded, group-empty, group-absent, ...); src/server/cors.ts:424-426, :516-523 (/base/ai/* open to first-party and owner-approved origins); src/routes/delegation.ts:1-10 (five routes), :78-110 (mode default read; root an absolute entity URI), :150-232 (session-grant: no right -> ForbiddenError; escalation 403; 201 note "dies on logout, on session expiry, on revoke, and on process restart. It is not a Base credential and cannot authenticate a fresh session."), :234-300 (revoke, session-granted, whoami Authorization: SessionDelegate <handle>, revoke-self); src/auth/session-delegate.ts:117 (1 h default), :121 (8 h max); src/auth/session-mint-gate.ts:42-67 (CSRF header, first-party Origin allow-list, live session, active account). Agent list read 2026-11-11 (4 picks). Repo team notes docs/BASE-DEVELOPER-GUIDE.md line 24 (slip, event: turn), not linked. No Dev.Guide chapter for the chat (Dev.Guide.Overview ReadNext lists none). READ only: no chat sent (it would need a person's token and Grok token). Rows: Developer.AiChatApi, DelegateToAgentInSession. Read 14 November 2026: the live answer Can I make an app that uses AI itself?

For developers

curl

agents.sh

# The agents the platform serves. No token is needed.
curl -s https://id.gilb.com/base/ai/agents

curl

chat.sh

# One turn as the signed-in person. The proof is new for this request.
curl -s -i https://id.gilb.com/base/ai/chat \
  -H "Authorization: DPoP <the person's token>" \
  -H "DPoP: <a new proof for POST https://id.gilb.com/base/ai/chat>" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Jackfruit","messages":[{"role":"user","content":"Which vaults can I reach?"}],
       "person_subscription":{"provider":"grok","access_token":"<the Grok access token>"}}'
# 200, headers x-standing-outcome: loaded, x-standing-group: ...
# {"role":"assistant","content":"...","model":"...","payer":"person-subscription"}

Checked against GilbApp d529620.