Referência da API: Choice / Score / yes-no

Decisões HTTP, auth, contratos de resposta e exemplos TypeScript para Choice, Score e yes-no.

A System One oferece escolhas, notas e probabilidades de sim/não estruturadas por HTTP. Esta referência cobre a API de decisão hospedada e os endpoints de conta do console. O SDK da System One também é um caminho de integração de primeira classe, com seus próprios adaptadores e credenciais. Comece pelo início rápido com o SDK hospedado para uma aplicação TypeScript, ou use os exemplos HTTP abaixo.

O que é a API da System One?

É a API de decisão hospedada para Choice, Score e Noul (yes-no). Autentique com uma chave de API e receba decisões tipadas para agentes.

Para erros, idempotência e versionamento, veja as páginas filhas em /pt-BR/docs/api/.

URL base e autenticação

Configuração	Valor
URL base	`https://system-one.dev/v1`
Endpoint de decisão e extração	`POST https://system-one.dev/v1/systemone`
Autenticação	`Authorization: Bearer YOUR_API_KEY`
Formato da requisição	`Content-Type: application/json`
Modelo	Copie o ID exato (`name`) da lista atual de modelos.

Crie uma chave de API no console da System One. Guarde-a no campo de segredo da sua ferramenta de integração ou no servidor, nunca em código de navegador, documentos compartilhados ou capturas de tela. Gerencie e revogue chaves no console. As requisições usam os créditos da sua conta.

A origem da API é o aplicativo principal, não o host de documentação. POST /v1/systemone exige uma chave Bearer da System One e aceita questions de decisão ou fields de extração; GET /v1/models é público. Os endpoints de conta /api/system-one/* usam a sessão do navegador conectada. A chave de API de um provedor direto não é uma chave de conta da System One.

YOUR_API_KEY, YOUR_MODEL_ID e YOUR_OPERATION_KEY abaixo são placeholders, não credenciais nem nomes de modelo válidos.

POST /v1/systemone
Authorization: Bearer $SYSTEM_ONE_API_KEY
Content-Type: application/json

GET /v1/models

Obtenha a lista atual de modelos. Este endpoint é público; um Bearer do chamador é ignorado e não provoca 401.

curl 'https://system-one.dev/v1/models' \
  -H 'Accept: application/json'

A resposta JSON é um objeto com um array models, não um array data. Não assuma uma quantidade ou ordem fixa de entradas.

Campo do modelo	Como usar
`name`	Valor exato a copiar para o campo `model` da requisição de decisão.
`displayName`	Nome legível para a seleção de modelo.
`description`	Descrição do modelo.
`pricing.creditsPerBlock`	Créditos por pergunta por bloco de cobrança.
`pricing.bytesPerBlock`	Número de bytes da requisição em um bloco de cobrança.
`capabilities.inputs`, `capabilities.questions`	Tipos de entrada e de pergunta suportados.
`limits`	Limites da requisição, incluindo `bytes` do corpo completo e as regras de pergunta.

Listar modelos não consome créditos de decisão e tem limite próprio de 60 requisições por IP com hash por minuto.

POST /v1/systemone

Substitua YOUR_MODEL_ID e salve o corpo como request.json:

{
  "model": "YOUR_MODEL_ID",
  "state": { "message": "I was charged twice for one order." },
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Choose the reviewing team.",
      "criteria": { "billing": "Payments and refunds", "support": "Technical help" }
    },
    "urgency": {
      "type": "score",
      "instructions": "Evaluate urgency with the ordered rubric.",
      "criteria": ["Normal review", "Timely response", "Immediate human attention"]
    },
    "duplicate": {
      "type": "noul",
      "instructions": "Does the message report a duplicate charge?"
    }
  }
}

Envie com a sua chave e uma chave de operação única, como um UUID. Salve a chave de operação e a requisição antes de enviar e reutilize-as apenas para recuperar a mesma operação.

curl --include 'https://system-one.dev/v1/systemone' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_OPERATION_KEY' \
  --data-binary @request.json

A resposta é JSON comum, não um stream. A chave de operação é opcional, mas sem ela uma requisição repetida é uma nova avaliação. Leia Chave de idempotência antes de ativar novas tentativas em uma ferramenta.

Campos da requisição

Campo	O que enviar
`model`	O `name` da entrada escolhida do catálogo, uma string não vazia de no máximo 128 caracteres. Envie explicitamente para não depender de um padrão.
`state`	Contexto compartilhado obrigatório: string, objeto JSON ou array. `""` é permitido, inclusive em tarefas só com imagem. Um array é um contexto compartilhado, não um lote de requisições.
`images`	Array ordenado opcional de `ImageInput`: strings de data URL base64 embutidas ou objetos com `mediaType` e `base64`. Apenas modelos compatíveis com imagens aceitam um array não vazio; `[]` é compatível com texto.
`questions`	Objeto com 1 a 32 perguntas nomeadas.
`questions.*.type`	`choice`, `score` ou `noul`. O tipo HTTP de uma probabilidade yes-no é `noul`, não `boolean`.
`questions.*.instructions`	String não vazia explicando a pergunta. Objetos e arrays JSON também são aceitos; alguns modelos exigem este campo.
`criteria` de Choice	Objeto que mapeia nomes de opção para descrições. Máximo: 255.
`criteria` de Score	Array de 2 a 10 descrições ordenadas, começando no índice zero. Use descrições não nulas.
`criteria` de Noul	Objeto opcional com descrições `true` e/ou `false`. Omita quando não for necessário.

Limites e custo

Limite	Máximo do serviço
Corpo da requisição em JSON UTF-8	`limits.bytes` do modelo: 65.536 bytes para modelos só de texto; até 13.631.488 bytes para entradas compatíveis com imagens
Imagens em modelos suportados	Até 4; até 4 MB decodificados por imagem e 8 MB decodificados no total
Perguntas por requisição	32
Opções por Choice	255
Níveis ordenados por Score	10, com mínimo de 2
Profundidade de aninhamento JSON	32

Um modelo selecionado pode impor limites mais estritos. Envie JSON UTF-8 válido sem chaves de objeto duplicadas. Os limites de conta são compartilhados entre chaves de API e requisições do Playground, e o limite padrão de decisão é de 120 requisições por minuto.

O consumo de créditos é calculado por blocos: blocks = max(1, ceil(bytes / pricing.bytesPerBlock)) e credits = número de perguntas × blocks × pricing.creditsPerBlock. O preço por modelo é um dado vivo do catálogo; consulte o campo pricing atual antes de uma nova operação. Veja Faturamento e créditos.

Lendo o resultado

Esta resposta ilustrativa mostra os formatos das respostas, não uma saída registrada. ACTUAL_MODEL_ID representa o nome de modelo devolvido pelo serviço.

{
  "model": "ACTUAL_MODEL_ID",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.8, "support": 0.2 },
      "confidence": 0.6
    },
    "urgency": {
      "type": "score",
      "score": 1.5,
      "probabilities": { "0": 0.1, "1": 0.3, "2": 0.6 },
      "confidence": 0.3,
      "legend": { "0": "Normal review", "1": "Timely response", "2": "Immediate human attention" }
    },
    "duplicate": { "type": "noul", "noul": 0.8 }
  },
  "usage": { "input_tokens": 120, "output_tokens": 0 }
}

Os nomes das respostas correspondem aos nomes das perguntas. Choice devolve um nome de opção; score pode ser fracionário; noul é a probabilidade de verdadeiro, de 0 a 1. A confiança é uma estatística separada do modelo, não necessariamente a probabilidade da opção selecionada. Contagens de token ausentes ou nulas significam desconhecido, não zero. O model devolvido pode diferir do ID solicitado; registre os dois.

O SDK core com systemOneAdapter normaliza Noul em { type: 'boolean', probability } e o uso de tokens em camelCase; ele não devolve todos os campos brutos. Para acesso HTTP completo, use Fetch ou o withResponse() do cliente TypeSafe oficial.

Cabeçalhos de resposta

Cabeçalho	Significado
`X-Request-Id`	ID da requisição na System One, a ser guardado para suporte; um replay bem-sucedido mantém o ID original.
`X-System-One-Credits`	Cobrança nova desta tentativa. Zero em um replay bem-sucedido ou um reembolso confirmado. Cabeçalho ausente não significa zero.
`X-Idempotency-Replayed`	`true` quando um resultado anterior bem-sucedido é devolvido sem nova avaliação ou cobrança.
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`	Limite da janela aplicável, tentativas restantes e instante de reset em timestamp Unix em segundos.
`Retry-After`	Tempo de espera em segundos ou uma data HTTP antes de repetir.
`X-System-One-Error-Code`	Classificação estável de erro; veja Códigos de erro da API.
`X-System-One-Error-Source`	`upstream` para um erro JSON encaminhado do serviço de modelo, `platform` para um erro da System One.

A contabilização da plataforma não está no corpo: use esses cabeçalhos e os registros de uso do console, não campos do corpo com nomes parecidos. As respostas usam Cache-Control: no-store.

Extração

Quando o corpo inclui fields, este endpoint extrai valores tipados em vez de responder perguntas de decisão. Envie uma requisição com { model, state, fields }, mais images, reference_date e options opcionais. O nome público do modelo de extração é clairic. Modelos de extração rejeitam questions; modelos de decisão rejeitam fields. Veja Extrair campos com Clairic.

Exemplos TypeScript

O SDK expõe os mesmos contratos de decisão e extração com resultados tipados:

import { createSystemOne, choice, score, booleanQuestion } from '@system-one-ai/core';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';
import { createFetchTransport } from '@system-one-ai/transport-fetch';

const client = createSystemOne({
  apiKey: process.env.SYSTEM_ONE_API_KEY,
  baseURL: 'https://system-one.dev/v1',
  model: process.env.SYSTEM_ONE_MODEL,
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  timeoutMs: 30_000,
  maxRetries: 0,
});

const result = await client.evaluate({
  state: { message: 'I was charged twice for the same order.' },
  questions: {
    team: choice('Choose the reviewing team.', {
      billing: 'Payments and refunds',
      support: 'Technical help',
    }),
    urgency: score('Rate urgency using this ordered rubric.', [
      'Routine review', 'Timely response', 'Immediate human attention',
    ]),
    duplicate: booleanQuestion('Does the message report a duplicate charge?'),
  },
});

console.log({
  team: result.answers.team.choice,
  urgency: result.answers.urgency.score,
  duplicateProbability: result.answers.duplicate.probability,
});

Para o cliente oficial independente e a leitura de cabeçalhos, veja o início rápido.

Limites e erros

Erros de autenticação e de validação inicial ocorrem antes de uma nova reserva de decisão e não cobram créditos. Os erros usam um envelope estável com error.code, error.message e request_id. Consulte Códigos de erro da API para a classificação por status HTTP e o que fazer em cada caso, e Chave de idempotência para recuperação de requisições interrompidas.

Para o contrato completo, o documento OpenAPI em https://system-one.dev/openapi.json é a referência pública autenticada. Não use operações que não estejam lá.

O que é a API da System One?

É a API de decisão hospedada para Choice, Score e Noul (yes-no). Autentique com uma chave de API e receba decisões tipadas para agentes.

Para erros, idempotência e versionamento, veja as páginas filhas em /pt-BR/docs/api/.

URL base e autenticação

Configuração	Valor
URL base	`https://system-one.dev/v1`
Endpoint de decisão e extração	`POST https://system-one.dev/v1/systemone`
Autenticação	`Authorization: Bearer YOUR_API_KEY`
Formato da requisição	`Content-Type: application/json`
Modelo	Copie o ID exato (`name`) da lista atual de modelos.

YOUR_API_KEY, YOUR_MODEL_ID e YOUR_OPERATION_KEY abaixo são placeholders, não credenciais nem nomes de modelo válidos.

POST /v1/systemone
Authorization: Bearer $SYSTEM_ONE_API_KEY
Content-Type: application/json

GET /v1/models

Obtenha a lista atual de modelos. Este endpoint é público; um Bearer do chamador é ignorado e não provoca 401.

curl 'https://system-one.dev/v1/models' \
  -H 'Accept: application/json'

A resposta JSON é um objeto com um array models, não um array data. Não assuma uma quantidade ou ordem fixa de entradas.

Campo do modelo	Como usar
`name`	Valor exato a copiar para o campo `model` da requisição de decisão.
`displayName`	Nome legível para a seleção de modelo.
`description`	Descrição do modelo.
`pricing.creditsPerBlock`	Créditos por pergunta por bloco de cobrança.
`pricing.bytesPerBlock`	Número de bytes da requisição em um bloco de cobrança.
`capabilities.inputs`, `capabilities.questions`	Tipos de entrada e de pergunta suportados.
`limits`	Limites da requisição, incluindo `bytes` do corpo completo e as regras de pergunta.

Listar modelos não consome créditos de decisão e tem limite próprio de 60 requisições por IP com hash por minuto.

POST /v1/systemone

Substitua YOUR_MODEL_ID e salve o corpo como request.json:

{
  "model": "YOUR_MODEL_ID",
  "state": { "message": "I was charged twice for one order." },
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Choose the reviewing team.",
      "criteria": { "billing": "Payments and refunds", "support": "Technical help" }
    },
    "urgency": {
      "type": "score",
      "instructions": "Evaluate urgency with the ordered rubric.",
      "criteria": ["Normal review", "Timely response", "Immediate human attention"]
    },
    "duplicate": {
      "type": "noul",
      "instructions": "Does the message report a duplicate charge?"
    }
  }
}

Envie com a sua chave e uma chave de operação única, como um UUID. Salve a chave de operação e a requisição antes de enviar e reutilize-as apenas para recuperar a mesma operação.

curl --include 'https://system-one.dev/v1/systemone' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_OPERATION_KEY' \
  --data-binary @request.json

Campos da requisição

Campo	O que enviar
`model`	O `name` da entrada escolhida do catálogo, uma string não vazia de no máximo 128 caracteres. Envie explicitamente para não depender de um padrão.
`state`	Contexto compartilhado obrigatório: string, objeto JSON ou array. `""` é permitido, inclusive em tarefas só com imagem. Um array é um contexto compartilhado, não um lote de requisições.
`images`	Array ordenado opcional de `ImageInput`: strings de data URL base64 embutidas ou objetos com `mediaType` e `base64`. Apenas modelos compatíveis com imagens aceitam um array não vazio; `[]` é compatível com texto.
`questions`	Objeto com 1 a 32 perguntas nomeadas.
`questions.*.type`	`choice`, `score` ou `noul`. O tipo HTTP de uma probabilidade yes-no é `noul`, não `boolean`.
`questions.*.instructions`	String não vazia explicando a pergunta. Objetos e arrays JSON também são aceitos; alguns modelos exigem este campo.
`criteria` de Choice	Objeto que mapeia nomes de opção para descrições. Máximo: 255.
`criteria` de Score	Array de 2 a 10 descrições ordenadas, começando no índice zero. Use descrições não nulas.
`criteria` de Noul	Objeto opcional com descrições `true` e/ou `false`. Omita quando não for necessário.

Limites e custo

Limite	Máximo do serviço
Corpo da requisição em JSON UTF-8	`limits.bytes` do modelo: 65.536 bytes para modelos só de texto; até 13.631.488 bytes para entradas compatíveis com imagens
Imagens em modelos suportados	Até 4; até 4 MB decodificados por imagem e 8 MB decodificados no total
Perguntas por requisição	32
Opções por Choice	255
Níveis ordenados por Score	10, com mínimo de 2
Profundidade de aninhamento JSON	32

Lendo o resultado

Esta resposta ilustrativa mostra os formatos das respostas, não uma saída registrada. ACTUAL_MODEL_ID representa o nome de modelo devolvido pelo serviço.

{
  "model": "ACTUAL_MODEL_ID",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.8, "support": 0.2 },
      "confidence": 0.6
    },
    "urgency": {
      "type": "score",
      "score": 1.5,
      "probabilities": { "0": 0.1, "1": 0.3, "2": 0.6 },
      "confidence": 0.3,
      "legend": { "0": "Normal review", "1": "Timely response", "2": "Immediate human attention" }
    },
    "duplicate": { "type": "noul", "noul": 0.8 }
  },
  "usage": { "input_tokens": 120, "output_tokens": 0 }
}

Cabeçalhos de resposta

Cabeçalho	Significado
`X-Request-Id`	ID da requisição na System One, a ser guardado para suporte; um replay bem-sucedido mantém o ID original.
`X-System-One-Credits`	Cobrança nova desta tentativa. Zero em um replay bem-sucedido ou um reembolso confirmado. Cabeçalho ausente não significa zero.
`X-Idempotency-Replayed`	`true` quando um resultado anterior bem-sucedido é devolvido sem nova avaliação ou cobrança.
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`	Limite da janela aplicável, tentativas restantes e instante de reset em timestamp Unix em segundos.
`Retry-After`	Tempo de espera em segundos ou uma data HTTP antes de repetir.
`X-System-One-Error-Code`	Classificação estável de erro; veja Códigos de erro da API.
`X-System-One-Error-Source`	`upstream` para um erro JSON encaminhado do serviço de modelo, `platform` para um erro da System One.

A contabilização da plataforma não está no corpo: use esses cabeçalhos e os registros de uso do console, não campos do corpo com nomes parecidos. As respostas usam Cache-Control: no-store.

Extração

Exemplos TypeScript

O SDK expõe os mesmos contratos de decisão e extração com resultados tipados:

import { createSystemOne, choice, score, booleanQuestion } from '@system-one-ai/core';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';
import { createFetchTransport } from '@system-one-ai/transport-fetch';

const client = createSystemOne({
  apiKey: process.env.SYSTEM_ONE_API_KEY,
  baseURL: 'https://system-one.dev/v1',
  model: process.env.SYSTEM_ONE_MODEL,
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  timeoutMs: 30_000,
  maxRetries: 0,
});

const result = await client.evaluate({
  state: { message: 'I was charged twice for the same order.' },
  questions: {
    team: choice('Choose the reviewing team.', {
      billing: 'Payments and refunds',
      support: 'Technical help',
    }),
    urgency: score('Rate urgency using this ordered rubric.', [
      'Routine review', 'Timely response', 'Immediate human attention',
    ]),
    duplicate: booleanQuestion('Does the message report a duplicate charge?'),
  },
});

console.log({
  team: result.answers.team.choice,
  urgency: result.answers.urgency.score,
  duplicateProbability: result.answers.duplicate.probability,
});

Para o cliente oficial independente e a leitura de cabeçalhos, veja o início rápido.

Limites e erros

Para o contrato completo, o documento OpenAPI em https://system-one.dev/openapi.json é a referência pública autenticada. Não use operações que não estejam lá.

Referência da API

O que é a API da System One?

URL base e autenticação

GET /v1/models

POST /v1/systemone

Campos da requisição

Limites e custo

Lendo o resultado

Cabeçalhos de resposta

Extração

Exemplos TypeScript

Limites e erros

Nesta página

Referência da API

O que é a API da System One?

URL base e autenticação

GET /v1/models

POST /v1/systemone

Campos da requisição

Limites e custo

Lendo o resultado

Cabeçalhos de resposta

Extração

Exemplos TypeScript

Limites e erros

Nesta página