API 레퍼런스: Choice / Score / yes-no

Choice / Score / yes-no의 HTTP 의사결정, 인증, 응답 계약과 TypeScript 예시.

System One은 HTTP로 구조화된 선택, 점수, yes/no 확률을 제공합니다. 이 레퍼런스는 호스팅 의사결정 API와 콘솔의 계정 엔드포인트를 다룹니다. 독립 System One SDK도 자체 어댑터와 자격 증명을 갖는一等급 통합 경로입니다. TypeScript 애플리케이션은 호스팅 SDK 퀵스타트로 시작하거나 아래 HTTP 예제를 사용하세요.

기본 URL과 인증

항목	값
기본 URL	`https://system-one.dev/v1`
의사결정·추출 엔드포인트	`POST https://system-one.dev/v1/systemone`
인증	`Authorization: Bearer YOUR_API_KEY`
요청 형식	`Content-Type: application/json`
모델	현재 모델 목록에서 정확한 모델 ID(`name`)를 복사하세요.

System One 콘솔에서 API 키를 만드세요. 통합 도구의 비밀 필드나 서버에 보관하고 브라우저 코드, 공유 문서, 스크린샷에 넣지 마세요. 콘솔에서 키를 관리하고 폐기할 수 있습니다. 요청은 계정의 크레딧을 사용합니다.

API 오리진은 문서 호스트가 아니라 메인 애플리케이션입니다. POST /v1/systemone은 System One Bearer 키를 요구하고 의사결정 questions 또는 추출 fields를 받습니다. GET /v1/models는 공개입니다. /api/system-one/* 계정 엔드포인트는 로그인한 브라우저 세션을 사용합니다. 제공자의 API 키는 System One 계정 키가 아닙니다.

아래의 YOUR_API_KEY, YOUR_MODEL_ID는 자리표시자입니다. 모델 자리표시자는 실제 카탈로그 ID로 교체하세요.

엔드포인트

엔드포인트	인증	용도
`GET /v1/models`	공개	현재 `{ models: [...] }` 카탈로그. 의사결정 크레딧이나 요청 기록을 만들지 않습니다. 호출자의 Bearer는 무시됩니다.
`POST /v1/systemone`	Bearer 키	의사결정(`questions`) 또는 추출(`fields`) 실행.
`GET /api/system-one/config`	공개	기본 모델, 계약, 준비 상태, 모델 카탈로그, 한도, 웰컴 크레딧, 콘솔 기능 제공 여부.
`GET /api/system-one/keys`	로그인 세션	키 메타데이터와 접두사 목록.
`POST /api/system-one/keys`	세션 + 동일 오리진	`{ "name": "Server" }`로 키 생성. 시크릿은 한 번만 반환됩니다.
`DELETE /api/system-one/keys/:id`	세션 + 동일 오리진	키 폐기.
`GET /api/system-one/usage`	로그인 세션	현재 잔액, 최근 30 UTC일 사용량, 그 구간의 최근 50개 요청.
`POST /api/system-one/playground`	세션 + 동일 오리진	`/v1/systemone`과 같은 요청 계약과 크레딧 정산으로 의사결정 제출.

공개 계약은 https://system-one.dev/openapi.json입니다. 이 문서에 없는 동작을 추가하지 마세요.

요청 본문

YOUR_MODEL_ID를 교체하고 이 본문을 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?"
    }
  }
}

키와 고유한 작업 키(UUID 등)를 붙여 보내세요. 보내기 전에 작업 키와 요청을 저장하고, 같은 작업을 복구할 때만 둘을 재사용합니다.

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

작업 키는 선택 사항이지만, 키 없이 요청을 반복하면 새 평가가 됩니다. 도구에서 재시도를 켜기 전에 멱등성과 재시도를 읽으세요.

요청 필드 요약:

필드	보낼 값
`model`	카탈로그 항목의 `name`. 항상 명시적으로 보내고 기본값에 의존하지 마세요.
`state`	필수 공유 컨텍스트: 문자열, JSON 객체, 배열. 빈 문자열도 허용됩니다. 배열은 하나의 공유 컨텍스트이며 여러 요청 묶음이 아닙니다.
`questions`	1–32개의 이름 있는 질문 객체.
`questions.*.type`	`choice`, `score`, `noul`. yes/no 확률의 HTTP 타입은 `boolean`이 아니라 `noul`입니다.
`questions.*.instructions`	질문을 설명하는 비어 있지 않은 문자열. 일부 모델은 이 필드를 요구합니다.
Choice `criteria`	옵션 이름과 설명을 연결하는 객체. 최대 255개.
Score `criteria`	2–10개의 순서 있는 설명 배열. 0번 인덱스부터 시작합니다.
Noul `criteria`	선택 사항인 `true`/`false` 설명 객체.

응답 읽기

아래는 답의 형태를 보여주는 예시이며, 실제 기록된 출력이 아닙니다. ACTUAL_MODEL_ID는 서비스가 반환한 모델 이름 자리표시자입니다.

{
  "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 }
}

noul은 0부터 1 사이의 참일 확률입니다. confidence는 별도의 모델 통계이며 선택된 옵션의 확률과 같지 않을 수 있습니다. 반환된 model은 요청한 ID와 다를 수 있으니 둘 다 기록하세요. 누락되거나 null인 토큰 수는 알 수 없는 상태이지 0이 아닙니다.

과금 정보는 본문이 아니라 헤더에 있습니다. X-Request-Id, X-System-One-Credits, X-Idempotency-Replayed, X-RateLimit-* 헤더를 읽으세요. 자세한 헤더 목록은 API 에러 코드와 멱등성과 재시도를 보세요.

TypeScript에서 호출하기

import { createSystemOne, choice } 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: process.env.SYSTEM_ONE_BASE_URL,
  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 team that should review this message.', {
      billing: 'Payments and refunds',
      support: 'Technical help',
      review: 'More information is needed',
    }),
  },
});

console.log({
  team: result.answers.team.choice,
  probabilities: result.answers.team.probabilities,
  requestId: result.response.requestId,
});

설치와 설정은 TypeScript SDK 시작하기, 결과 의미는 의사결정 프리미티브를 보세요.

항목	값
기본 URL	`https://system-one.dev/v1`
의사결정·추출 엔드포인트	`POST https://system-one.dev/v1/systemone`
인증	`Authorization: Bearer YOUR_API_KEY`
요청 형식	`Content-Type: application/json`
모델	현재 모델 목록에서 정확한 모델 ID(`name`)를 복사하세요.

아래의 YOUR_API_KEY, YOUR_MODEL_ID는 자리표시자입니다. 모델 자리표시자는 실제 카탈로그 ID로 교체하세요.

엔드포인트

엔드포인트	인증	용도
`GET /v1/models`	공개	현재 `{ models: [...] }` 카탈로그. 의사결정 크레딧이나 요청 기록을 만들지 않습니다. 호출자의 Bearer는 무시됩니다.
`POST /v1/systemone`	Bearer 키	의사결정(`questions`) 또는 추출(`fields`) 실행.
`GET /api/system-one/config`	공개	기본 모델, 계약, 준비 상태, 모델 카탈로그, 한도, 웰컴 크레딧, 콘솔 기능 제공 여부.
`GET /api/system-one/keys`	로그인 세션	키 메타데이터와 접두사 목록.
`POST /api/system-one/keys`	세션 + 동일 오리진	`{ "name": "Server" }`로 키 생성. 시크릿은 한 번만 반환됩니다.
`DELETE /api/system-one/keys/:id`	세션 + 동일 오리진	키 폐기.
`GET /api/system-one/usage`	로그인 세션	현재 잔액, 최근 30 UTC일 사용량, 그 구간의 최근 50개 요청.
`POST /api/system-one/playground`	세션 + 동일 오리진	`/v1/systemone`과 같은 요청 계약과 크레딧 정산으로 의사결정 제출.

공개 계약은 https://system-one.dev/openapi.json입니다. 이 문서에 없는 동작을 추가하지 마세요.

요청 본문

YOUR_MODEL_ID를 교체하고 이 본문을 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?"
    }
  }
}

키와 고유한 작업 키(UUID 등)를 붙여 보내세요. 보내기 전에 작업 키와 요청을 저장하고, 같은 작업을 복구할 때만 둘을 재사용합니다.

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

작업 키는 선택 사항이지만, 키 없이 요청을 반복하면 새 평가가 됩니다. 도구에서 재시도를 켜기 전에 멱등성과 재시도를 읽으세요.

요청 필드 요약:

필드	보낼 값
`model`	카탈로그 항목의 `name`. 항상 명시적으로 보내고 기본값에 의존하지 마세요.
`state`	필수 공유 컨텍스트: 문자열, JSON 객체, 배열. 빈 문자열도 허용됩니다. 배열은 하나의 공유 컨텍스트이며 여러 요청 묶음이 아닙니다.
`questions`	1–32개의 이름 있는 질문 객체.
`questions.*.type`	`choice`, `score`, `noul`. yes/no 확률의 HTTP 타입은 `boolean`이 아니라 `noul`입니다.
`questions.*.instructions`	질문을 설명하는 비어 있지 않은 문자열. 일부 모델은 이 필드를 요구합니다.
Choice `criteria`	옵션 이름과 설명을 연결하는 객체. 최대 255개.
Score `criteria`	2–10개의 순서 있는 설명 배열. 0번 인덱스부터 시작합니다.
Noul `criteria`	선택 사항인 `true`/`false` 설명 객체.

응답 읽기

아래는 답의 형태를 보여주는 예시이며, 실제 기록된 출력이 아닙니다. ACTUAL_MODEL_ID는 서비스가 반환한 모델 이름 자리표시자입니다.

{
  "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 }
}

TypeScript에서 호출하기

import { createSystemOne, choice } 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: process.env.SYSTEM_ONE_BASE_URL,
  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 team that should review this message.', {
      billing: 'Payments and refunds',
      support: 'Technical help',
      review: 'More information is needed',
    }),
  },
});

console.log({
  team: result.answers.team.choice,
  probabilities: result.answers.team.probabilities,
  requestId: result.response.requestId,
});

설치와 설정은 TypeScript SDK 시작하기, 결과 의미는 의사결정 프리미티브를 보세요.

API 레퍼런스

기본 URL과 인증

엔드포인트

요청 본문

응답 읽기

TypeScript에서 호출하기

자주 묻는 질문

다음 문서

이 페이지의 내용

API 레퍼런스

기본 URL과 인증

엔드포인트

요청 본문

응답 읽기

TypeScript에서 호출하기

자주 묻는 질문

다음 문서

이 페이지의 내용