Build a useful conversation, keep context under control and handle every outcome. Start with the current HTTP contract, real access requirements and examples you can inspect.
The published chat API works on the Galactre origin. Model availability, session eligibility and service health are checked separately.
Guest chat
No login or browser API key. Discover the current session, inspect its limits and submit a Lunar text request when available. History belongs to that guest session.
Enabled in configuration
Configured message limit: 2,000 characters. The session endpoint is authoritative for your allowance.
Sign in through Galactre for separate account history and workspace features. The browser uses a server-side session; service credentials stay on the server.
Guest conversations do not automatically migrate after login. Billing endpoints require an authenticated account.
Returns one published, integrity-checked report as an attachment. Includes all measured attempt hashes, usage and limitations. Draft and withdrawn reports, prompts and answer text are never exposed. No session or API key is required.
Outcomes 200: galactre.evaluation-report.v1 JSON. 404: malformed, missing or withdrawn report. 503: publication storage or integrity unavailable.
GET/api/v1/chat/modelsDiscover model availabilityPublic
Returns models, releases and catalog_available. Each model has a stable id, name, family, availability, lifecycle, description and published limits. Null specifications or rates mean not published; they do not mean unlimited or free. An unreachable catalog is distinct from an unavailable model.
Outcomes 200: catalog response. Read catalog_available and each model.available before selecting a family.
GET/api/v1/chat/sessionDiscover the current sessionBrowser session
Creates or resumes an eligible guest/account chat session. Returns authenticated, guest, chat_available, csrf_token and limits. Limits are null for signed-in sessions. Guest limits include remaining requests, reset/expiry information, message length and permitted model families.
Outcomes 200: session ready. 503: session or chat configuration unavailable. Keep the CSRF token in memory; never put it in a URL.
POST/api/v1/chat/generateGenerate a text responseSession + CSRF
Send message, model (family or exact release), optional conversation_id, request_key and stream. The family shorthand remains supported. With stream true, SSE delivers start, delta and completed; otherwise the endpoint returns JSON. Model planning for enabled tools is private; the final answer may stream. A durable request key prevents duplicate execution.
Outcomes 200: completed. 400/422: invalid input. 403: denied. 409: model unavailable. 429: limit reached. 503: unavailable or uncertain outcome.
Returns conversations for the current identity only, ordered by most recent update, up to 30 records. Each item includes id, title and updated_at. This is a bounded recent list without a pagination cursor.
Outcomes 200: { conversations: [...] }. 503: history or session unavailable. An empty array means no accessible recent conversations.
GET/api/v1/chat/conversations/{id}Read an owned conversationBrowser session
Use a saved 32-character lowercase hexadecimal conversation ID. Returns id and up to 100 recent messages in chronological order; messages contain id, role, content and created_at. The current identity must own the conversation.
Outcomes 200: conversation messages. 404: missing or inaccessible. 503: history unavailable. Knowing an ID does not grant access.
POST/api/v1/chat/conversations/{id}/deleteDelete a saved conversationSession + CSRF
Submit only after the user explicitly confirms deletion. Removes the owned conversation and its messages from the active store. Billing, security/audit records and backup retention have separate policies. This operation does not submit a model request.
Outcomes 200: { deleted: true }. 404: missing or inaccessible. 503: storage unavailable. Update the interface only after success.
POST/api/v1/responsesCreate a server responseBearer key + Idempotency-Key
Send message, explicit model, optional conversation_id and stream. A key only grants its configured GT families and uses its owner balance. Server keys cannot delegate private knowledge or tools.
Outcomes 200=>inspect the returned state. 401/403=>access denied. 404=>inaccessible resource. 409=>conflict. 429=>rate limit. 503=>unavailable or unconfirmed.
GET/api/v1/responses/{id}Read a server requestBearer key
Read durable state and an encrypted saved result under the same owner account. Never retry an uncertain request with a new idempotency key.
Outcomes 200=>inspect the returned state. 401/403=>access denied. 404=>inaccessible resource. 409=>conflict. 429=>rate limit. 503=>unavailable or unconfirmed.
POST/api/v1/responses/{id}/cancelStop a server responseBearer key
Request server transport cancellation. The response may have already completed; otherwise consumed tokens and uncertain provider outcomes remain subject to metering and reconciliation.
Outcomes 200=>inspect the returned state. 401/403=>access denied. 404=>inaccessible resource. 409=>conflict. 429=>rate limit. 503=>unavailable or unconfirmed.
Recover a request state after reconnecting. Owner and guest session boundaries still apply.
Outcomes 200=>inspect the returned state. 401/403=>access denied. 404=>inaccessible resource. 409=>conflict. 429=>rate limit. 503=>unavailable or unconfirmed.
POST/api/v1/chat/runs/{id}/cancelStop a browser responseSession + CSRF
Stops the active server transport. A local fetch abort alone does not prove a provider stopped or that no tokens were consumed.
Outcomes 200=>inspect the returned state. 401/403=>access denied. 404=>inaccessible resource. 409=>conflict. 429=>rate limit. 503=>unavailable or unconfirmed.
POST/api/v1/chat/recoverRecover delivery after a disconnectSession + CSRF
Send the original request_key. Returns the owned request state and retained final result when available. This endpoint never invokes a model. Expired results are removed while the idempotency record remains.
Outcomes 200=>inspect state and result. 404=>request not found for the current identity.
POST/api/v1/account/keysManage server keysAccount session + CSRF
Actions create, rotate and revoke manage owner-scoped credentials. Creation and rotation return plaintext once. GET on this path lists key metadata without verifiers or secrets.
Outcomes 200=>inspect the returned state. 401/403=>access denied. 404=>inaccessible resource. 409=>conflict. 429=>rate limit. 503=>unavailable or unconfirmed.
POST/api/v1/account/teamsManage teams and invitationsAccount session + CSRF
Create and rename teams, issue recipient-bound invitations, accept once with verified IAMC email, revoke invitations, change member roles or remove members. GET lists accessible team rosters. Only owners manage administrator roles or delete a team.
Outcomes 200=>inspect the returned state. 401/403=>access denied. 404=>inaccessible resource. 409=>conflict. 429=>rate limit. 503=>unavailable or unconfirmed.
Billing has separate authenticated operations for catalog, orders and reconciliation. Start in Credits and billing; the chat contract does not grant payment permissions.
03 / FIRST REQUEST
Discover. Authenticate. Generate. Inspect.
The JavaScript example checks the catalog and session before sending text. It is a same-origin browser example, without an external SDK. Request and response JSON are illustrative fixtures.
01
Read the catalog
Select a permitted family with available: true. A planned model cannot be enabled through a request.
02
Discover the session
Check chat_available, current guest limits and the CSRF token.
03
Send one focused task
Submit JSON with same-origin credentials. Disable duplicate sends while the request is pending.
04
Inspect the outcome
Accept completed results. Save the conversation ID if present and handle history failure independently.
SAME-ORIGIN BROWSER
// Run on the Galactre origin. Calling this function sends a generation request.
async function askGalactre(message, conversationId) {
const catalogResponse = await fetch('/api/v1/chat/models');
if (!catalogResponse.ok) throw new Error('Catalog unavailable.');
const catalog = await catalogResponse.json();
if (!catalog.models?.some(m => m.family === 'Lunar' && m.available)) {
throw new Error('Lunar is not currently available.');
}
const sessionResponse = await fetch('/api/v1/chat/session', {
credentials: 'same-origin'
});
const session = await sessionResponse.json();
if (!sessionResponse.ok || !session.chat_available || !session.csrf_token) {
throw new Error('Chat is temporarily unavailable.');
}
const text = message.trim();
const maxLength = session.limits?.max_message_chars ?? 8000;
if (!text || Array.from(text).length > maxLength) {
throw new Error('Check the message length before sending.');
}
// Retain this key for recovery; a retry with changed input must use a new key.
const requestKey = 'quickstart_' + crypto.randomUUID().replaceAll('-', '');
const body = { family: 'Lunar', model: 'gt-lunar', message: text, request_key: requestKey };
if (conversationId) body.conversation_id = conversationId;
const response = await fetch('/api/v1/chat/generate', {
method: 'POST', credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': session.csrf_token
},
body: JSON.stringify(body)
});
const result = await response.json();
if (response.status === 429) {
throw new Error('Rate limited. Retry-After: ' + response.headers.get('Retry-After'));
}
if (!response.ok || result.status !== 'completed') {
throw new Error('Inspect the request outcome before retrying.');
}
return {
text: result.response,
requestId: result.id,
conversationId: result.conversation_id,
historyState: result.history?.state ?? 'not_reported'
};
}
// Review the returned text. This function does not run code or tools.
ILLUSTRATIVE JSON · NO REQUEST EXECUTED
{
"model": "gt-lunar",
"family": "Lunar",
"message": "Explain the trade-offs in this design.",
"request_key": "example_0123456789abcdef",
"stream": true
}
// Server JavaScript, called explicitly. Obtain apiKey from your server secret store.
// Persist requestKey before sending; reuse it only with identical input.
async function askGTFromServer(origin, apiKey, message, requestKey) {
if (!/^[A-Za-z0-9_-]{16,100}$/.test(requestKey)) {
throw new Error('A durable request key is required.');
}
const response = await fetch(new URL('/api/v1/responses', origin), {
method: 'POST', credentials: 'omit', redirect: 'error',
headers: {
Authorization: 'Bearer ' + apiKey,
'Idempotency-Key': requestKey,
'Content-Type': 'application/json', Accept: 'application/json'
},
body: JSON.stringify({ model: 'gt-lunar', message, stream: false })
});
const result = await response.json();
// Inspect HTTP status AND result.status. Never automatically resend unknown work.
return { httpStatus: response.status, ...result };
}
// Read GET /api/v1/responses/{id} with the same authorized key to recover a result.
// POST /api/v1/responses/{id}/cancel requests Stop. Uncertain usage stays reserved.
// Set stream:true and Accept:text/event-stream to receive start/delta/completed events.
04 / REQUEST & RESPONSE
Know what you send. Know what you receive.
Content-Type is application/json. The browser never supplies internal credentials, execution configuration or an access object.
Generation request
stream / request_keyboolean / string · optional
Set stream true for SSE. Supply a durable browser request_key of 16–100 letters, numbers, underscores or hyphens for recovery before the first event. If omitted, the server creates one and you must retain the returned delivery ID. Reuse a key only with identical input. Server responses require the Idempotency-Key header.
messagestring · required
Non-empty trimmed UTF-8 text within the 4.2 MB request limit, model context and account budget. Unsafe control characters are rejected. Guest sessions have a smaller configured character limit; inspect session.limits.max_message_chars.
modelstring · family or exact release ID
For example gt-lunar follows the current default; gt-lunar-1 pins an available exact release. When model is supplied it selects the family.
familystring · default Lunar
Lunar, Stellar or Nebular. A valid name must also be available and permitted. Guest chat currently accepts only Lunar.
conversation_idstring · optional
32 lowercase hexadecimal characters from a saved exchange. Omit for a new conversation. Continue only under the identity that owns it.
Generation response
id / finish_reasonDelivery identity / completion reason
Use id for status and cancellation. finish_reason is stop, length, content_filter or unknown. A length-limited answer is billable completed usage; it may need a follow-up. An expired replay returns HTTP 410 and never invokes a model.
status / request_idExecution outcome
Accept text only when status is completed. Preserve request_id for diagnosis. An indeterminate result needs inspection before another submission.
response / public_identity / model_idGT result
Generated text and its GT product identity, such as GT Lunar 1 and gt-lunar-1. requested_model retains the original selection; model_family, model_version and release_hash describe the resolved release. Validate important content before using it.
usageReported consumption
Contains a state. Nonnegative prompt_tokens, completion_tokens and total_tokens appear when reported. Missing values are unknown, not zero.
conversation_id / historyOptional persistence result
conversation_id is returned when the exchange is saved. history.state = unavailable means a completed answer could not be saved. Do not assume it will appear after reloading.
guest_limitsGuest responses only
Updated session allowance when available. A displayed remainder does not bypass per-IP or service-wide admission checks.
Omit conversation_id. A saved exchange returns its ID; keep it only for the current session/account.
Continue
Reuse the saved ID. Recent messages are bounded by count and byte limits before being used as context. The history read endpoint can return more messages than a generation request includes.
Switch identity
Signing in opens separate account history. Guest expiry, logout or another identity can change which conversations are accessible.
Delete deliberately
Ask for confirmation, send the owned delete operation with CSRF, and remove it from the interface only after success. Active-store deletion does not erase separate billing or audit records.
06 / ERRORS & LIMITS
Treat each outcome as an operational decision.
Inspect HTTP status and the JSON body together. Errors can use message, error.code or a top-level code; an execution failure can be blocked or indeterminate. Do not assume every error has one uniform shape.
410
Retained result expired
The idempotency record remains, but its response retention period has ended. Replaying the command never dispatches another model request. Create a different command only for a deliberate new generation.
400 / 422
Fix the request
Check JSON, text length, control characters, family and conversation ID. An access object is rejected. Do not include service credentials or internal execution settings.
401 / 403
Check access
Billing requires login; chat may be denied by model or service policy. Do not loop on denied requests. Guest sessions do not grant account or billing permissions.
404
Check conversation ownership
A conversation is missing or inaccessible to the current identity. Start a new conversation or return to the account/session that created it.
409
Refresh model availability
The chosen family is unavailable. Recheck the catalog; changing a model name or purchasing credits does not activate it.
419
Refresh the session
The mutation failed its CSRF/session check. Obtain current session state. Check history and any previous outcome before resending a generation request.
429
Honor Retry-After
Guest admission limits may return error.code = guest_quota_exceeded, retry_after and a Retry-After header. Wait for the advised interval; avoid retry storms.
503
Preserve uncertainty
A dependency or history store may be unavailable. status = indeterminate means completion is unconfirmed. Inspect request ID and history before retrying; a browser timeout is not a cancellation guarantee.
07 / INTEGRATION CHECKS
Build the complete experience.
Validate failure paths as carefully as a successful reply. Example code does not activate production access, monitoring or external tools.
Use the documented identity
Use a same-origin session and CSRF for browser mutations. For a server integration, create an expiring key in API Access and keep it in your server secret store.
Build for limits
Validate text length, disable duplicate submissions while pending, honor 429 and distinguish a missing metric from zero usage.
Handle history independently
Keep the saved conversation ID, separate guest/account history and surface storage failure without pretending the answer was persisted.
Review before acting
Model text is a proposal. Your application must enforce authorization, validation and approval for writes, commands, payments or deployments.
Send model with a published exact ID, such as gt-lunar-1. A family ID follows its promoted default. Read requested_model, model_id, model_family, model_version and release_hash from completed responses. The releases list in model discovery contains available exact IDs. See Models / Versions & releases.
Where is the Galactre API base URL?
The paths on this page are relative to the Galactre origin you are using. The examples are for a page served by that same origin. Do not substitute a third-party endpoint or copy a browser session into a server application.
Can I create a Galactre API key here?
Sign in and open API Access to create, rotate or revoke a model-scoped server key. Use POST /api/v1/responses with a bearer key and an Idempotency-Key. This is the documented Galactre response contract; it is not an OpenAI-compatible API.
Is there an official SDK?
No separately versioned Galactre SDK is published by this project. The JavaScript here is a copyable example using the current HTTP contract, not an installed SDK or a background request runner.
Can I stream, cancel execution or call tools?
Set stream to true for SSE start, delta and completed events. Stop through the matching cancel endpoint; disconnects also interrupt the server transport. Provider usage may still need reconciliation. Signed-in chat supports selected private knowledge sources, calculator and current-time tools. File uploads and image generation are not released.
Can I supply an idempotency key or choose execution infrastructure?
Browser requests accept request_key; server requests require Idempotency-Key. Reuse a key with identical input to read or replay the original result. Different input returns 409. Request identity never selects infrastructure or grants access.
How much conversation context is included?
The service considers up to 510 recent saved messages, subject to per-message and total byte limits. Saved history and the model context window are different. See the Memory guide for the current boundaries.
BUILD WITH GALACTRE
Start with a conversation. Design what comes next.