# How do I use the AI chat API?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

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](http://support.gilb.com/help/how-do-i-use-the-sign-in-kit), and that person's own Grok access token.

## 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

   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](http://support.gilb.com/help/how-do-i-make-a-dpop-proof-for-each-request):
   POST https://id.gilb.com/base/ai/chat

   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.

   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](http://support.gilb.com/help/how-does-a-browser-app-get-the-owners-approval).

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](http://support.gilb.com/help/which-agents-are-there-and-which-do-i-use-for-what) 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 &lt;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

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

### curl: chat.sh

```curl
# 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"}
```
