User Claims¶

User claims são registros de chave-valor vinculados aos seus usuários que o assistant lê automaticamente em cada conversa. Eles dão ao assistant contexto sobre com quem está conversando — sem precisar de prompt engineering da sua parte.

Como os claims funcionam¶

Quando você envia uma request para /v1/responses com o header x-user-id, o Nodexa carrega todos os claims armazenados para aquele usuário e os injeta no contexto do assistant antes de gerar a resposta. O assistant vê o nome do usuário, função, preferências e quaisquer outros atributos que você armazenou — e usa essas informações naturalmente nas respostas.

Você não precisa colar dados do usuário no campo input. Armazene uma vez e cada conversa vai refletir automaticamente.

Autenticação¶

Todos os endpoints de User Claims requerem uma API key enviada como x-api-key ou Authorization: Bearer <key>.

-H "x-api-key: nxk_your_api_key_here"

Endpoints¶

Armazenar claims — `POST /v1/user-claims/bulk`¶

Cria ou atualiza múltiplos claims para um usuário em uma única request. Cada entrada é um upsert: se um claim com o mesmo userId + claimKey já existir, o valor é substituído.

Headers da request:

Header	Obrigatório	Descrição
`x-api-key`	Sim	Sua API key do Nodexa
`x-user-id`	Sim	O usuário cujos claims você está escrevendo
`Content-Type`	Sim	`application/json`

Corpo da requisição:

{
  "claims": [
    { "claimKey": "name", "claimValue": "Ada Lovelace" },
    { "claimKey": "preferred_language", "claimValue": "pt-BR" },
    { "claimKey": "role", "claimValue": "software_engineer" },
    { "claimKey": "subscription_plan", "claimValue": "pro" }
  ]
}

Campo	Obrigatório	Tipo	Descrição
`claims`	Sim	`array`	Array de objetos de claim
`claims[].claimKey`	Sim	`string`	Nome do claim. Use `snake_case`. Máx 255 chars.
`claims[].claimValue`	Sim	`any`	Qualquer valor JSON. Máx 64KB total por usuário.

Resposta — 201 Created:

{
  "count": 2
}

TypeScript / fetchOpenAI SDK (Node.js)curl

const BASE_URL = 'https://app.nodexa.cloud';

async function setUserClaims(userId: string, claims: Record<string, unknown>) {
  const body = {
    claims: Object.entries(claims).map(([claimKey, claimValue]) => ({
      claimKey,
      claimValue,
    })),
  };

  const res = await fetch(`${BASE_URL}/v1/user-claims/bulk`, {
    method: 'POST',
    headers: {
      'x-api-key': process.env.NODEXA_API_KEY!,
      'x-user-id': userId,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });

  if (!res.ok) throw new Error(`Failed to set claims: ${res.status}`);
  return res.json();
}

// No cadastro ou atualização de perfil do usuário
await setUserClaims('user_abc123', {
  name: 'Ada Lovelace',
  preferred_language: 'pt-BR',
  role: 'software_engineer',
  subscription_plan: 'pro',
});

Use fetch para escrever claims e deixe o SDK lidar com as conversas:

import OpenAI from 'openai';

const BASE_URL = 'https://app.nodexa.cloud';

const client = new OpenAI({
  baseURL: `${BASE_URL}/v1`,
  apiKey: process.env.NODEXA_API_KEY!,
  defaultHeaders: {
    'x-user-id': 'user_abc123',
  },
});

// 1. Armazene claims antes (ou a qualquer momento antes) da conversa
await fetch(`${BASE_URL}/v1/user-claims/bulk`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.NODEXA_API_KEY!,
    'x-user-id': 'user_abc123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    claims: [
      { claimKey: 'name', claimValue: 'Ada Lovelace' },
      { claimKey: 'preferred_language', claimValue: 'pt-BR' },
    ],
  }),
});

// 2. O assistant agora conhece o nome e o idioma do usuário automaticamente
const response = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID!,
  input: 'What features are available in my plan?',
});

console.log(response.output_text);

curl https://app.nodexa.cloud/v1/user-claims/bulk \
  -X POST \
  -H "x-api-key: nxk_your_api_key_here" \
  -H "x-user-id: user_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "claims": [
      { "claimKey": "name",               "claimValue": "Ada Lovelace" },
      { "claimKey": "preferred_language", "claimValue": "pt-BR" },
      { "claimKey": "role",               "claimValue": "software_engineer" },
      { "claimKey": "subscription_plan",  "claimValue": "pro" }
    ]
  }'

Recuperar claims — `GET /v1/user-claims/:userId`¶

Retorna todos os claims armazenados para um usuário.

Parâmetros de path:

Parâmetro	Tipo	Descrição
`userId`	`string`	O identificador do usuário

Resposta — 200 OK:

{
  "claims": [
    {
      "claimKey": "name",
      "claimValue": { "name": "Alice", "job": "Engineer" }
    },
    {
      "claimKey": "preferred_language",
      "claimValue": "pt-BR"
    }
  ],
  "userId": "user_abc123",
  "organizationId": "org_abc"
}

Nota: claimValue pode ser qualquer valor JSON — uma string, número, booleano, array ou objeto.

TypeScript / fetchcurl

const res = await fetch(
  `https://app.nodexa.cloud/v1/user-claims/user_abc123`,
  { headers: { 'x-api-key': process.env.NODEXA_API_KEY! } }
);

const { claims, userId, organizationId } = await res.json();
console.log(claims);

curl "https://app.nodexa.cloud/v1/user-claims/user_abc123" \
  -H "x-api-key: nxk_your_api_key_here"

Excluir um claim — `DELETE /v1/user-claims/:userId/:claimKey`¶

Remove permanentemente um único claim.

Parâmetros de path:

Parâmetro	Tipo	Descrição
`userId`	`string`	O identificador do usuário
`claimKey`	`string`	A chave do claim a excluir

Resposta: 200 OK em caso de sucesso. 404 se o claim não existir.

TypeScript / fetchcurl

const res = await fetch(
  `https://app.nodexa.cloud/v1/user-claims/user_abc123/preferred_language`,
  {
    method: 'DELETE',
    headers: { 'x-api-key': process.env.NODEXA_API_KEY! },
  }
);

if (res.ok) {
  console.log('Claim deleted');
} else if (res.status === 404) {
  console.log('Claim not found');
}

curl "https://app.nodexa.cloud/v1/user-claims/user_abc123/preferred_language" \
  -X DELETE \
  -H "x-api-key: nxk_your_api_key_here"

Como o assistant usa os claims¶

Quando um usuário envia uma mensagem, o Nodexa automaticamente:

Busca todos os claims para o x-user-id fornecido na request.
Serializa os claims em um bloco de contexto estruturado.
Insere esse bloco no contexto de sistema do assistant antes da chamada ao LLM.

O resultado é que o assistant sempre sabe com quem está conversando. Se um usuário tem preferred_language: "pt-BR", o assistant responde em português — sem precisar de prompt adicional. Se um usuário tem role: "data_analyst", o assistant adapta as explicações de acordo.

Os claims não são visíveis em output_text

Os claims são injetados como contexto de sistema, não como parte do histórico de conversa que o usuário vê. Eles influenciam as respostas de forma transparente.

Boas Práticas¶

Nomenclatura de chaves de claim¶

Use snake_case, nomes descritivos. Mantenha as chaves estáveis — mudar o nome de uma chave efetivamente cria um novo claim e abandona o antigo.

Bom	Evitar
`name`	`n`, `userName`
`preferred_language`	`lang`, `language_preference_value`
`subscription_plan`	`plan_type_current`
`role`	`jobRole`, `user_role_string`
`timezone`	`tz`, `user_tz_code`

O que armazenar¶

Foque em fatos estáveis e reutilizáveis sobre o usuário que vão ser úteis em várias interações com o assistant:

Identidade: name, email (se necessário para chamadas de tool)
Localização: preferred_language, timezone, locale
Função / acesso: role, subscription_plan, team
Personalização: communication_style (por exemplo, "concise" vs "detailed"), industry

Evite armazenar dados de sessão efêmeros ou blobs grandes — use o campo input no corpo da request para isso.

Sincronizando com seu banco de dados de usuários¶

Chame o endpoint bulk sempre que um usuário for criado ou seu perfil mudar:

async function syncUserToNodexa(user: {
  id: string;
  fullName: string;
  locale: string;
  plan: string;
  role: string;
}) {
  await fetch('https://app.nodexa.cloud/v1/user-claims/bulk', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.NODEXA_API_KEY!,
      'x-user-id': user.id,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      claims: [
        { claimKey: 'name', claimValue: user.fullName },
        { claimKey: 'preferred_language', claimValue: user.locale },
        { claimKey: 'subscription_plan', claimValue: user.plan },
        { claimKey: 'role', claimValue: user.role },
      ],
    }),
  });
}

Limites¶

Limite	Valor
Armazenamento total máximo de claims por usuário	64KB
Máximo de claims por request bulk	50
Comprimento máximo de `claimKey`	255 caracteres

Confira Limites para a referência completa.