Envie uma pergunta ao GQueries. Receba evidências seguras.

Comece aqui

Imagine um caderno que verifica respostas.

Você só precisa entender dois momentos: primeiro ensina ao caderno as informações confiáveis; depois, seus usuários fazem perguntas sobre elas.

// This code runs on your server, never in the browser.
const response = await fetch("https://api.gqueries.com/v1/memories", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ALETHEION_API_KEY}`,
    "Content-Type": "application/json",
    // A new value every time your server creates a new memory.
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    memory_id: `purchase:${order.id}`,
    namespace_id: process.env.ALETHEION_NAMESPACE_ID,
    occurred_at: new Date().toISOString(),
    content: "Order 1042 was paid and delivered: wireless mouse, black.",
    content_type: "text/plain",
    source_id: "orders:1042",
    authorization_labels: ["customer", "approved"],
  }),
});

const memory = await response.json();

// "pending" means GQueries is indexing it. Later it becomes "indexed".
return memory;

// This code runs on your server, never in the browser.
const response = await fetch("https://api.gqueries.com/v1/ground", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ALETHEION_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    namespace_id: process.env.ALETHEION_NAMESPACE_ID,
    input: userInput,
  }),
});

const { grounded_answer } = await response.json();

// Show the checked answer to the user.
return grounded_answer;

Não coloque a pergunta do usuário em /v1/memories. Uma memória é algo confiável que o sistema poderá usar depois. Uma pergunta é apenas um pedido de resposta. Misturar os dois ensinaria ao caderno que toda pergunta é um fato.

Antes de gravar uma preferência ou compra: seu backend deve saber a quem ela pertence, por que está correta e quem pode usá-la. Nunca transforme uma mensagem de chat não verificada, um palpite do modelo ou um dado privado de outro cliente em memória.

Opção avançada: POST /v1/queries retorna evidências autorizadas sem invocar o reader. Use somente quando seu backend precisar controlar diretamente a inferência do reader.

Comece aqui

O que o GQueries faz — e o que não faz.

Sua IA já possui um reader: o modelo que escreve a resposta final. O GQueries atua antes dele. Armazena memória aprovada, encontra evidências relevantes para uma pergunta e decide se elas são seguras o bastante para permitir a entrega.

01

A integração em quatro etapas.

Seu backend faz dois tipos essenciais de chamada: uma para armazenar informações aprovadas e outra para encontrar evidências para uma pergunta. Nada sensível deve ser chamado diretamente do navegador.

02

Conecte seu backend, não o navegador.

Sua API key identifica a empresa, o projeto e o ambiente autorizados a fazer a requisição. Trate-a como uma senha do servidor. Uma pessoa usando seu site nunca deve ver nem enviar essa chave.

02A

Separe os usuários do portal dos usuários da sua aplicação.

Existem dois planos de identidade. Usuários do portal são pessoas da sua equipe que administram a conta. Usuários, compradores, pacientes, agentes ou visitantes do seu produto permanecem no seu próprio sistema de identidade e não se registram no GQueries.

Equipes: use um projeto separado quando uma aplicação precisar de credenciais e ciclo de vida independentes. Créditos de uso e cobrança pertencem atualmente à organização, não a um projeto individual. Use um namespace quando vários usuários estiverem intencionalmente autorizados a recuperar as mesmas evidências dentro de um projeto.

02B

Escolha namespaces gerenciados ou delegados.

A hierarquia de autorização é organization → project → environment → namespace. A API key fixa os três primeiros níveis. Uma requisição pode selecionar somente um namespace dentro dessa fronteira; não pode escolher outra empresa.

Escopos da API key

Menor privilégio: um assistente interno fixo normalmente não precisa de namespace:provision. Uma aplicação multiusuário geralmente precisa. Emita uma chave de servidor por aplicação e ambiente e faça a rotação quando a propriedade ou o deployment mudar.

Mapeie as identidades do seu domínio no backend

// server/aletheion-identity.ts
// Your application owns users and sessions. Aletheion receives only a stable,
// pseudonymous namespace ID selected by your trusted backend.
type GroundingSubject =
  | { kind: "customer"; customerId: string }
  | { kind: "workspace"; workspaceId: string }
  | { kind: "session"; sessionId: string };

export function namespaceFor(subject: GroundingSubject): string {
  // Every source ID must be a UUID generated and persisted by your application.
  // Never put an email address, phone number or display name in a namespace ID.
  if (subject.kind === "customer") return "customer:" + subject.customerId;
  if (subject.kind === "workspace") return "workspace:" + subject.workspaceId;
  return "session:" + subject.sessionId;
}

// Use the resulting namespace in both memory writes and grounding queries.
// A key with namespace:provision creates it idempotently on first use, but only
// inside the organization, project and environment already bound to that key.
const namespaceId = namespaceFor({
  kind: "session",
  sessionId: "018f5f42-55f1-7d3a-a2ca-8f44b73a9c10",
});

Privacidade: IDs de namespace são seletores, não perfis. Use UUIDs opacos. Nunca codifique neles e-mail, identificadores fiscais, telefone, nome, texto do prompt ou credenciais do reader.

Transição de identidade: não copie evidências silenciosamente entre namespaces anônimos e autenticados. Vinculação, promoção ou exclusão exigem uma política explícita de consentimento e retenção na sua aplicação.

03

Copie uma implementação completa de servidor.

Defina três variáveis de ambiente no backend. Copie o ID do namespace do dashboard ou derive-o sob um prefixo delegado aprovado. A API key e o seletor de namespace nunca devem ser commitados no Git nem expostos ao navegador.

ALETHEION_BASE_URL=https://api.gqueries.com
ALETHEION_API_KEY=<key-issued-in-your-dashboard>
ALETHEION_NAMESPACE_ID=support:550e8400-e29b-41d4-a716-446655440000

// server/aletheion.ts
// Keep this module on your backend. Importing it into browser code would expose
// the customer API key and allow unauthorized requests from end-user devices.

// Allow staging or local environments to override the API host. Production uses
// GQueries's stable public domain by default.
const ALETHEION_BASE_URL =
  process.env.ALETHEION_BASE_URL ??
  "https://api.gqueries.com";

// Read the organization-scoped credential from the server environment. GQueries
// issues this key after provisioning; never hard-code or commit its plaintext value.
const ALETHEION_API_KEY = process.env.ALETHEION_API_KEY;
if (!ALETHEION_API_KEY) throw new Error("ALETHEION_API_KEY is missing");
const ALETHEION_NAMESPACE_ID = process.env.ALETHEION_NAMESPACE_ID;
if (!ALETHEION_NAMESPACE_ID) throw new Error("ALETHEION_NAMESPACE_ID is missing");

// Send one authenticated request to GQueries and decode its JSON response.
// T is the response shape expected by the calling function; in production, generate
// these types from the approved OpenAPI v1 contract.
async function aletheion<T>(path: string, init: RequestInit): Promise<T> {
  const response = await fetch(`${ALETHEION_BASE_URL}${path}`, {
    ...init,
    headers: {
      // The bearer key determines organization, project and environment authority.
      Authorization: `Bearer ${ALETHEION_API_KEY}`,
      "Content-Type": "application/json",
      // Preserve endpoint-specific headers such as Idempotency-Key.
      ...init.headers,
    },
    // Stop waiting after 30 seconds instead of leaving a request open indefinitely.
    signal: AbortSignal.timeout(30_000),
  });

  const body = await response.json();
  if (!response.ok) {
    // Real applications should also record body.error.correlation_id for support,
    // while keeping credentials and memory content out of logs.
    throw new Error(`Aletheion ${body.error?.code ?? response.status}`);
  }
  return body as T;
}

// Store one canonical memory that future queries may retrieve as evidence.
// The returned state is normally "pending"; wait for "indexed" before testing it.
export async function storeMemory(content: string) {
  // memory_id identifies this source fact throughout updates, deletion and auditing.
  const memoryId = `memory:${crypto.randomUUID()}`;
  return aletheion("/v1/memories", {
    method: "POST",
    // A unique idempotency key makes a retry safe without creating a duplicate write.
    // Reuse this same value only when retrying this exact intended request.
    headers: { "Idempotency-Key": crypto.randomUUID() },
    body: JSON.stringify({
      memory_id: memoryId,
      // Replace this example with a stable boundary from your own access model.
      namespace_id: ALETHEION_NAMESPACE_ID,
      // occurred_at is when the source event or fact became true, in RFC 3339 UTC.
      occurred_at: new Date().toISOString(),
      content,
      content_type: "text/plain",
      // source_id tells auditors which upstream system supplied the information.
      source_id: "support-policy-system",
      // Labels restrict which authorized contexts may receive this memory.
      authorization_labels: ["support", "approved"],
      metadata: { version: "1" },
    }),
  });
}

// Retrieve authorized evidence for a question. This function does not call an LLM
// and does not generate the final answer; your application invokes its BYOK reader
// only after inspecting the evidence and grounding decision.
export async function findEvidence(question: string) {
  return aletheion("/v1/queries", {
    method: "POST",
    body: JSON.stringify({
      // A new query ID lets usage and audit records trace this operation end to end.
      query_id: `query:${crypto.randomUUID()}`,
      // The query must use a namespace authorized for the current customer context.
      namespace_id: ALETHEION_NAMESPACE_ID,
      question,
      asked_at: new Date().toISOString(),
      // Request at most five candidates; policy checks may return fewer or abstain.
      top_k: 5,
    }),
  });
}

# aletheion.py
# Keep this module on your backend so the customer API key never reaches a browser.
import os
import uuid
from datetime import datetime, timezone

import httpx

# Permit an explicit staging/local host while defaulting to the production API.
BASE_URL = os.getenv(
    "ALETHEION_BASE_URL",
    "https://api.gqueries.com",
)
# Fail immediately at startup when the provisioned server credential is absent.
API_KEY = os.environ["ALETHEION_API_KEY"]
NAMESPACE_ID = os.environ["ALETHEION_NAMESPACE_ID"]

# Reuse one authenticated client with a bounded timeout.
client = httpx.Client(
    base_url=BASE_URL,
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=30.0,
)

def store_memory(content: str) -> dict:
    # Idempotency makes an exact network retry safe; memory_id tracks the source fact.
    response = client.post(
        "/v1/memories",
        headers={"Idempotency-Key": str(uuid.uuid4())},
        json={
            "memory_id": f"memory:{uuid.uuid4()}",
            # Replace this with a stable namespace from your authorization model.
            "namespace_id": NAMESPACE_ID,
            "occurred_at": datetime.now(timezone.utc).isoformat(),
            "content": content,
            "content_type": "text/plain",
            # Identify the upstream source and the contexts allowed to receive it.
            "source_id": "support-policy-system",
            "authorization_labels": ["support", "approved"],
            "metadata": {"version": "1"},
        },
    )
    response.raise_for_status()
    # This response is normally pending; wait for indexed before testing retrieval.
    return response.json()

def find_evidence(question: str) -> dict:
    # Retrieve authorized evidence only. Your BYOK reader remains a separate call.
    response = client.post(
        "/v1/queries",
        json={
            "query_id": f"query:{uuid.uuid4()}",
            "namespace_id": NAMESPACE_ID,
            "question": question,
            "asked_at": datetime.now(timezone.utc).isoformat(),
            # Ask for at most five candidates; validation can return fewer or abstain.
            "top_k": 5,
        },
    )
    response.raise_for_status()
    return response.json()

04

Siga um fluxo de requisição controlado.

O GQueries verifica qual empresa está chamando, qual namespace ela pode acessar, se cada memória está vigente e se pode ser divulgada. Configure o provedor, o modelo e a API key criptografada em Reader BYOK. A conta do provedor e os custos de tokens continuam sob responsabilidade da sua empresa.

05

Armazene informações nas quais seu sistema possa confiar.

Envie a requisição ao endereço completo de produção abaixo. Uma memória deve vir de uma origem conhecida e pertencer a um namespace claro. A chave de idempotência exclusiva torna segura a repetição após uma interrupção de rede: a mesma gravação não será armazenada duas vezes.

curl -X POST "https://api.gqueries.com/v1/memories" \
  -H "Authorization: Bearer $ALETHEION_API_KEY" \
  -H "Idempotency-Key: 01J-example-unique-write" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_id": "policy:refund:v1",
    "namespace_id": "support:550e8400-e29b-41d4-a716-446655440000",
    "occurred_at": "2026-08-13T12:00:00Z",
    "content": "Refunds are available within the approved policy window.",
    "content_type": "text/plain",
    "source_id": "policy-system:refunds",
    "authorization_labels": ["support", "approved"]
  }'

{
  "memory_id": "policy:refund:v1",
  "namespace_id": "support:550e8400-e29b-41d4-a716-446655440000",
  "state": "pending",
  "revision": 1
}

O que acontece depois: pending significa que o GQueries aceitou a memória, mas a recuperação ainda está sendo preparada. Use-a somente depois que se tornar indexed. Memória com falha, excluída ou revogada não pode ser divulgada como evidência ativa.

Aguarde até a memória ser indexada

O pipeline de produção é assíncrono. Consulte GET /v1/memories/{memory_id} antes de esperar que uma memória recém-gravada apareça na recuperação.

// The POST returns state "pending". Wait before querying this memory.
async function waitUntilIndexed(memoryId: string) {
  for (let attempt = 0; attempt < 30; attempt += 1) {
    const memory = await aletheion<{ state: string }>(
      `/v1/memories/${encodeURIComponent(memoryId)}`,
      { method: "GET" },
    );
    if (memory.state === "indexed") return memory;
    if (memory.state === "failed") throw new Error("Memory indexing failed");
    await new Promise((resolve) => setTimeout(resolve, 1_000));
  }
  throw new Error("Memory indexing timed out");
}

06 · Avançado

Recupere evidências sem chamar o reader.

A maioria das integrações deve usar /v1/ground. Use https://api.gqueries.com/v1/queries somente quando seu backend quiser o pacote de evidências e operar sua própria chamada ao reader.

curl -X POST "https://api.gqueries.com/v1/queries" \
  -H "Authorization: Bearer $ALETHEION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query_id": "query:01JEXAMPLE",
    "namespace_id": "support:550e8400-e29b-41d4-a716-446655440000",
    "question": "What is the approved refund policy?",
    "asked_at": "2026-08-13T12:05:00Z",
    "top_k": 5
  }'

Importante: top_k: 5 solicita no máximo cinco candidatos. Isso não garante cinco resultados; evidências não autorizadas, desatualizadas ou inválidas são removidas.

07

Deixe a decisão controlar a entrega.

A ação de grounding não é uma pontuação de qualidade nem uma sugestão. Ela informa o que sua aplicação pode fazer em seguida.

Nunca transforme block ou abstain em uma chamada não fundamentada ao reader. Uma citação anexada em algum ponto da resposta não justifica outra alegação sem suporte.

07

Uso e cobrança

Uma operação finalizada como accepted, reduced, rejected ou abstained consome uma query de grounding pré-paga. Uma falha interna reverte a reserva. Como a resposta final do reader não é reproduzida, reutilizar um query_id concluído retorna HTTP 409 idempotency_replay_unavailable e não consome outra unidade.

08

Trate erros estruturados

Decida o fluxo por error.code, nunca pela mensagem legível. Guarde o correlation ID retornado para suporte sem registrar conteúdo de memória ou segredos.

09

Checklist de produção

• Use uma API key por projeto e ambiente.
• Derive a autoridade da organização das credenciais, nunca do corpo da requisição.
• Use namespaces estáveis e o mínimo necessário de labels.
• Gere uma nova chave de idempotência para cada gravação pretendida.
• Configure as credenciais do reader somente pela página autenticada Reader BYOK; nunca as exponha no código do navegador.
• Respeite block e abstain sem recorrer a palpites.
• Registre correlation IDs e ações de grounding na trilha de auditoria.
• Teste o isolamento entre tenants antes do tráfego de produção.