このページは、エンジンのバージョン 0.16.0 のコードから生成しています。リリースとリリースの間は main のコードを表示するため、次のバージョンの変更がすでに入っていることがあります。
Pointsman の HTTP API です。どのリクエストにも、ヘッダー Authorization: Bearer <token> で API トークンを付けます。OpenAPI を読むツール向けの完全な定義は openapi.yaml にあります。
コードから取り込んだ説明文は英語のままです。
Get a decision from a profile.
| パラメーター | 場所 | 必須 | 説明 |
|---|
profile | path | はい | |
version | query | いいえ | Profile version. The latest version when not given. |
Idempotency-Key | header | いいえ | A repeated request with the same key from the same client gets the decision already logged, when the request is the same (profile and version, state, ref, decisions); a different request with the same key is refused (409 idempotency_conflict). Ignored for test tokens, whose decisions are not logged. |
リクエストボディ: DecideRequest(JSON)
| ステータス | 説明 | ボディ |
|---|
| 200 | The decision | Decision (application/json) |
| 400 | Error | Error (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 403 | The token may not use this profile. | Error (application/json) |
| 404 | Error | Error (application/json) |
| 409 | resolved_by_person: the decision this one would replace was resolved by a person, and a person’s answer stays (docs/decision-chains.md). idempotency_conflict: the Idempotency-Key was used for a different request. | Error (application/json) |
| 500 | Error | Error (application/json) |
| 502 | Error | Error (application/json) |
Get a logged decision with its feedback.
| ステータス | 説明 | ボディ |
|---|
| 200 | The decision as logged | DecisionRecord (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 403 | A test token, which may only decide. | Error (application/json) |
| 404 | Unknown decision, or one whose profile this token may not use. | Error (application/json) |
| 500 | Error | Error (application/json) |
Correct the answers of a decision.
Corrections are checked against the profile version the decision used.
A decision can get feedback more than once; all of it is kept.
リクエストボディ: FeedbackRequest(JSON)
| ステータス | 説明 | ボディ |
|---|
| 204 | Feedback stored | |
| 400 | Error | Error (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 403 | A test token, which may only decide. | Error (application/json) |
| 404 | Unknown decision, or one whose profile this token may not use. | Error (application/json) |
| 409 | The profile version of the decision is no longer available. | Error (application/json) |
| 500 | Error | Error (application/json) |
What happened to a profile’s decisions in the last days.
Counts only, no single decisions or states: decisions per action, the
review queue (pending, resolved, the final actions people chose), and
decisions where a person corrected at least one answer. The window
applies to when a decision was made; a later resolution or correction
of such a decision counts with it.
| パラメーター | 場所 | 必須 | 説明 |
|---|
profile | path | はい | |
days | query | いいえ | The window, from 1 to 90 days back from now (default 7). |
| ステータス | 説明 | ボディ |
|---|
| 200 | The counts | ProfileStats (application/json) |
| 400 | Error | Error (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 403 | The token may not use this profile. | Error (application/json) |
| 404 | Unknown profile. | Error (application/json) |
| 500 | Error | Error (application/json) |
List decisions waiting for a human review.
Decisions with action review that are not resolved yet, oldest first (at most 100), for the profiles this token may use.
| パラメーター | 場所 | 必須 | 説明 |
|---|
profile | query | いいえ | |
| ステータス | 説明 | ボディ |
|---|
| 200 | Pending reviews | object (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 403 | The token may not use this profile, or it is a test token (it may only decide). | Error (application/json) |
| 500 | Error | Error (application/json) |
Resolve a pending review.
Sets the final action and answers. Answers in correct replace the
model’s (source human); the others are kept (source model).
correct is also stored as feedback. When the decision has a
callback_url, the final answer is sent there (see “Callbacks”).
リクエストボディ: ResolveRequest(JSON)
| ステータス | 説明 | ボディ |
|---|
| 200 | Resolved | Resolution (application/json) |
| 400 | Error | Error (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 403 | A test token, which may only decide. | Error (application/json) |
| 404 | Unknown decision, or one whose profile this token may not use. | Error (application/json) |
| 409 | The decision has no pending review (not a review, already resolved, or closed as superseded), or its profile version is gone. | Error (application/json) |
| 500 | Error | Error (application/json) |
Close a pending review of your own decision.
The review leaves the queue as superseded, for example when the
question it asks no longer applies (the GitHub connector closes the
review of an older commit after a push). Only the client that made
the decision may close it; for any other token the decision does not
exist (404). No body. No callback is sent, and a later resolve gets
409 not_pending.
| ステータス | 説明 | ボディ |
|---|
| 200 | Closed | ClosedReview (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 403 | A test token, which may only decide. | Error (application/json) |
| 404 | Unknown decision, one whose profile this token may not use, or one another client made. | Error (application/json) |
| 409 | The decision has no pending review (not a review, already resolved, or closed). | Error (application/json) |
| 500 | Error | Error (application/json) |
List the profiles this token may use, with their versions.
| ステータス | 説明 | ボディ |
|---|
| 200 | The profiles this token may use (all profiles for a token with scope *) | object (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 500 | Error | Error (application/json) |
The decision graph a profile belongs to, for DMN tools.
The profile, the profiles it requires and the ones that require it
(docs/decision-chains.md), among the profiles this token may use, as
a DMN decision requirements graph. Only the graph: no decision logic.
With format=dmn, DMN 1.3 XML with DMNDI shapes, which DMN tools
(bpmn.io dmn-js, Camunda Modeler, Apache KIE) open. Not for test tokens.
| パラメーター | 場所 | 必須 | 説明 |
|---|
id | path | はい | |
format | query | いいえ | json (the graph), dmn (DMN 1.3 XML with DMNDI) or svg (a small diagram in the style of the datamodels.jp diagrams). |
lang | query | いいえ | The language of the svg diagram’s text. |
| ステータス | 説明 | ボディ |
|---|
| 200 | The graph | DecisionGraph (application/json) |
| 400 | Error | Error (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 403 | The token may not use this profile (also a test token). | Error (application/json) |
| 404 | Error | Error (application/json) |
| 500 | Error | Error (application/json) |
A profile in plain sentences.
The profile as plain sentences in English or Japanese, for the people
who approve it (docs/profile-format.md#explain): which model answers,
what it sees, the questions, facts and earlier decisions, and each rule
as “If …, the action is …”. The rules are read with the engine’s own
parser. A required profile out of this token’s scope is not named, and a
rule that reads it is shown as written. Test tokens may use it too: it
reads no decisions.
| パラメーター | 場所 | 必須 | 説明 |
|---|
id | path | はい | |
version | query | いいえ | A published version; the latest when not given. |
lang | query | いいえ | |
format | query | いいえ | json (the parts), or text (Markdown, to show as it is). |
| ステータス | 説明 | ボディ |
|---|
| 200 | The explanation | ProfileExplanation (application/json) |
| 400 | Error | Error (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 403 | The token may not use this profile. | Error (application/json) |
| 404 | Error | Error (application/json) |
| 500 | Error | Error (application/json) |
Try a changed policy on the logged decisions.
What a changed policy would have decided on the newest logged decisions
of a published version (docs/profile-format.md#replay). Policy only: the
logged answers and facts are used, no model is called, and questions,
facts and requires must stay the same (send them to have them checked).
Earlier decisions are read from the snapshot kept with each decision; a
new rule that reads a value the snapshot did not keep is unknown there,
and the decision is counted as inexact. The token must be allowed to use
the profile and every profile it requires. Not for test tokens.
リクエストボディ: object(JSON)
| ステータス | 説明 | ボディ |
|---|
| 200 | The replay | ReplayResult (application/json) |
| 400 | Error | Error (application/json) |
| 401 | Missing, malformed, unknown or revoked token. | Error (application/json) |
| 403 | The token may not use this profile or a profile it requires (also a test token). | Error (application/json) |
| 404 | Error | Error (application/json) |
| 409 | The draft’s questions, facts or requires differ from the version (not_policy_only). | Error (application/json) |
| 500 | Error | Error (application/json) |
| フィールド | 型 | 必須 | 説明 |
|---|
state | string | object | array | はい | What the model decides about: free text, or any JSON object or array. When the profile has an input mapping, this is the raw client payload the mapping reads from. |
ref | string | いいえ | The client’s reference for this decision, for example an issue id. |
callback_url | string | いいえ | Where to send the final answer after a human review (https only). |
decisions | object | いいえ | For a profile with requires (docs/decision-chains.md): the ids of the earlier decisions, by the names in requires. They are read from the decision log and must be of the named profile, in the token’s scope, with this request’s ref (then required) and from the same client; every other case gives the same 400. An optional one that was made for an older decision than one given here is left out (it is missing from requires in the answer). Not for test tokens. |
A profile in plain sentences (docs/profile-format.md#explain).
| フィールド | 型 | 必須 | 説明 |
|---|
profile | string | はい | |
version | integer | はい | |
lang | “en” | “ja” | はい | |
title | string | はい | |
description | string | はい | |
model | string | はい | Which model answers |
input | string | はい | What the model sees of the request. |
questions | string[] | はい | |
facts | string[] | はい | |
requires | string[] | はい | |
rules | object[] | はい | In order; the first rule that matches gives the action. |
order | string | はい | How the rules are checked. |
default | string | はい | The action when no rule matches |
people | string[] | はい | Which actions a person checks |
notes | string[] | はい | |
A changed policy replayed on logged decisions (docs/profile-format.md#replay).
| フィールド | 型 | 必須 | 説明 |
|---|
profile | string | はい | |
version | integer | はい | The version whose decisions were replayed. |
replayed | integer | はい | Decisions replayed exactly; all other numbers count only these. |
from | string | null | はい | The oldest replayed decision. |
to | string | null | はい | The newest replayed decision. |
inexact | integer | はい | Decisions not replayed because a new rule reads a value of an earlier decision that was not kept. |
skipped | integer | はい | Decisions not replayed because an answer the new rules read is not in the log. |
changed | integer | はい | Decisions whose action would change. |
actions | object | はい | |
transitions | object[] | はい | |
people | object | はい | |
changes | object[] | はい | Up to 50 changed decisions, newest first. |
| フィールド | 型 | 必須 | 説明 |
|---|
action | string | はい | |
rule | integer | null | はい | |
A DMN decision requirements graph; node and edge types are DMN’s names.
| フィールド | 型 | 必須 | 説明 |
|---|
profile | string | はい | The profile the graph was asked for. |
nodes | object[] | はい | |
edges | object[] | はい | |
What the rules read from one required decision, when this decision was made.
| フィールド | 型 | 必須 | 説明 |
|---|
decision | string | はい | |
profile | string | はい | |
profile_version | integer | はい | |
action | string | はい | |
outcome | string | はい | The person’s answer when a review was resolved |
reviewed | boolean | はい | |
read | object | はい | Every value the rules read from it, by path; null = unknown. |
A required decision of a profile the reader may not see.
| フィールド | 型 | 必須 | 説明 |
|---|
decision_id | string | はい | |
ref | string | いいえ | |
answers | object | はい | One answer per question, keyed by question name. |
action | string | はい | auto, review, or a custom action defined by the profile. |
profile | string | はい | |
profile_version | integer | はい | |
model | string | はい | The model that answered. |
created_at | string | はい | When the decision was made. |
rule | integer | null | はい | Index of the policy rule that matched (from 0); null when the default action applied. |
facts | Facts | いいえ | Only for profiles with facts (docs/profile-format.md#facts): each fact the profile asked for, by name, as looked up for this decision, or why it is missing. A rule that needs a missing fact does not match. |
test | true | いいえ | Present (true) only for a test token’s decision, which is not logged. |
requires | object | いいえ | For a profile with requires, by name. A required decision of a profile the token may no longer use is hidden. |
replaces | string | いいえ | The earlier decision of the same profile, ref and client that this one replaces. |
review | object | いいえ | Present when a person checks the decision before it counts (the profile’s people_check). |
versions | Versions | いいえ | The engine version and the fact modules that answered the decision’s facts, with their versions (docs/modules.md). Missing for decisions made before fact modules. |
The engine version and the fact modules that answered the decision’s facts, with their versions (docs/modules.md). Missing for decisions made before fact modules.
| フィールド | 型 | 必須 | 説明 |
|---|
engine | string | はい | |
modules | object | はい | Module name to version, for example “@pointsman/github”. |
| フィールド | 型 | 必須 | 説明 |
|---|
profile | string | はい | |
days | integer | はい | |
since | string | はい | Decisions made at or after this time are counted. |
decisions | integer | はい | |
actions | object | はい | Decisions per action. |
reviews | object | はい | |
corrected | integer | はい | Decisions where a person corrected at least one answer (as in docs/accuracy.sql). |
型: openapi.yaml を参照
| フィールド | 型 | 必須 | 説明 |
|---|
decision_id | string | はい | |
created_at | string | はい | |
client | string | はい | The client whose token made the decision. |
ref | string | いいえ | |
profile | string | はい | |
profile_version | integer | はい | |
model | string | はい | |
action | string | はい | |
rule | integer | null | はい | Index of the policy rule that matched; null when the default action applied. |
answers | object | はい | |
facts | Facts | いいえ | Only for profiles with facts (docs/profile-format.md#facts): each fact the profile asked for, by name, as looked up for this decision, or why it is missing. A rule that needs a missing fact does not match. |
state_hash | string | はい | SHA-256 of the state sent to the model (keys sorted). |
state | | いいえ | The state sent to the model. Only when the profile sets log.store_state. |
review | Review | いいえ | Only for decisions whose action a person checks (the profile’s people_check; default review). |
requires | object | いいえ | For a profile with requires, by name. A required decision of a profile the reader may not see is hidden. |
idempotency_key | string | いいえ | The Idempotency-Key the decision was made with. |
replaces | string | いいえ | The earlier decision of the same profile |
versions | Versions | いいえ | The engine version and the fact modules that answered the decision’s facts, with their versions (docs/modules.md). Missing for decisions made before fact modules. |
discarded_at | string | いいえ | Made while a person resolved the decision it would replace; the client got 409 resolved_by_person and it never counts. |
Only for decisions whose action a person checks (the profile’s people_check; default review).
| フィールド | 型 | 必須 | 説明 |
|---|
status | “pending” | “resolved” | “superseded” | はい | superseded: a newer decision replaced this one while the review was open, or the client that made it closed the review. |
resolved_at | string | いいえ | |
resolved_by | string | いいえ | |
final_action | string | いいえ | |
final_answers | FinalAnswers | いいえ | |
型: object
Delivery of the final answer to the decision’s callback_url.
| フィールド | 型 | 必須 | 説明 |
|---|
status | “pending” | “delivered” | “failed” | はい | |
attempts | integer | はい | |
last_error | string | いいえ | |
next_at | string | いいえ | |
| フィールド | 型 | 必須 | 説明 |
|---|
action | string | はい | The final action, e.g. auto; not review. |
correct | object | いいえ | Corrected answers by question name (as in feedback). Empty or left out to keep the model’s answers. |
by | string | はい | |
note | string | いいえ | |
| フィールド | 型 | 必須 | 説明 |
|---|
decision_id | string | はい | |
action | string | はい | |
answers | FinalAnswers | はい | |
resolved_by | string | はい | |
resolved_at | string | はい | |
callback | “pending” | “none” | はい | pending when the final answer will be sent to the callback_url. |
| フィールド | 型 | 必須 | 説明 |
|---|
decision_id | string | はい | |
review | object | はい | |
| フィールド | 型 | 必須 | 説明 |
|---|
correct | object | はい | Corrected values by question name: true/false (noul), an option (choice), a level (score). |
by | string | はい | Who made the correction. |
note | string | いいえ | |
| フィールド | 型 | 必須 | 説明 |
|---|
created_at | string | はい | |
client | string | はい | |
by | string | はい | |
correct | object | はい | |
note | string | いいえ | |
Only for profiles with facts (docs/profile-format.md#facts): each fact the profile asked for, by name, as looked up for this decision, or why it is missing. A rule that needs a missing fact does not match.
型: object | object
型: NoulAnswer | ChoiceAnswer | ScoreAnswer
| フィールド | 型 | 必須 | 説明 |
|---|
type | “noul” | はい | |
value | boolean | はい | true when P(yes) >= 0.5 |
p | Probability | はい | |
yes | Probability | はい | |
| フィールド | 型 | 必須 | 説明 |
|---|
type | “choice” | はい | |
value | string | はい | The most likely option. |
p | Probability | はい | |
probabilities | Probabilities | はい | |
| フィールド | 型 | 必須 | 説明 |
|---|
type | “score” | はい | |
value | integer | はい | The most likely level |
p | Probability | はい | |
score | number | はい | Probability-weighted level; can fall between levels. |
probabilities | Probabilities | はい | Probability per level, keyed by level index. |
型: number
型: object
| フィールド | 型 | 必須 | 説明 |
|---|
id | string | はい | |
version | integer | はい | Latest version. |
versions | integer[] | はい | |
title | BilingualText | はい | |
description | BilingualText | はい | |
requires | string[] | いいえ | The profile ids the latest version requires (decision chains, docs/decision-chains.md). |
| フィールド | 型 | 必須 | 説明 |
|---|
en | string | はい | |
ja | string | はい | |
