HTTP API

This page is generated from the code of engine version 0.16.0. Between releases, the site shows the code on main, which may already have changes for the next version.

The Pointsman HTTP API. Every request needs an API token in the header Authorization: Bearer <token>. The full description, for tools that read OpenAPI, is openapi.yaml.

POST /v1/decide/{profile}

Get a decision from a profile.

Parameter	In	Required	Description
profile	path	yes
version	query	no	Profile version. The latest version when not given.
Idempotency-Key	header	no	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.

Request body: DecideRequest (JSON).

Status	Description	Body
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 /v1/decisions/{id}

Get a logged decision with its feedback.

Parameter	In	Required	Description
id	path	yes

Status	Description	Body
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)

POST /v1/decisions/{id}/feedback

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.

Parameter	In	Required	Description
id	path	yes

Request body: FeedbackRequest (JSON).

Status	Description	Body
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)

GET /v1/stats/{profile}

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.

Parameter	In	Required	Description
profile	path	yes
days	query	no	The window, from 1 to 90 days back from now (default 7).

Status	Description	Body
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)

GET /v1/reviews

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.

Parameter	In	Required	Description
profile	query	no

Status	Description	Body
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)

POST /v1/reviews/{id}/resolve

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”).

Parameter	In	Required	Description
id	path	yes

Request body: ResolveRequest (JSON).

Status	Description	Body
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)

POST /v1/reviews/{id}/close

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.

Parameter	In	Required	Description
id	path	yes

Status	Description	Body
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)

GET /v1/profiles

List the profiles this token may use, with their versions.

Status	Description	Body
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)

GET /v1/profiles/{id}/graph

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.

Parameter	In	Required	Description
id	path	yes
format	query	no	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	no	The language of the svg diagram’s text.

Status	Description	Body
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)

GET /v1/profiles/{id}/explain

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.

Parameter	In	Required	Description
id	path	yes
version	query	no	A published version; the latest when not given.
lang	query	no
format	query	no	json (the parts), or text (Markdown, to show as it is).

Status	Description	Body
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)

POST /v1/profiles/{id}/replay

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.

Parameter	In	Required	Description
id	path	yes

Request body: object (JSON).

Status	Description	Body
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)

Schemas

DecideRequest

Field	Type	Required	Description
state	string | object | array	yes	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	no	The client’s reference for this decision, for example an issue id.
callback_url	string	no	Where to send the final answer after a human review (https only).
decisions	object	no	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.

ProfileExplanation

A profile in plain sentences (docs/profile-format.md#explain).

Field	Type	Required	Description
profile	string	yes
version	integer	yes
lang	“en” | “ja”	yes
title	string	yes
description	string	yes
model	string	yes	Which model answers
input	string	yes	What the model sees of the request.
questions	string[]	yes
facts	string[]	yes
requires	string[]	yes
rules	object[]	yes	In order; the first rule that matches gives the action.
order	string	yes	How the rules are checked.
default	string	yes	The action when no rule matches
people	string[]	yes	Which actions a person checks
notes	string[]	yes

ReplayResult

A changed policy replayed on logged decisions (docs/profile-format.md#replay).

Field	Type	Required	Description
profile	string	yes
version	integer	yes	The version whose decisions were replayed.
replayed	integer	yes	Decisions replayed exactly; all other numbers count only these.
from	string | null	yes	The oldest replayed decision.
to	string | null	yes	The newest replayed decision.
inexact	integer	yes	Decisions not replayed because a new rule reads a value of an earlier decision that was not kept.
skipped	integer	yes	Decisions not replayed because an answer the new rules read is not in the log.
changed	integer	yes	Decisions whose action would change.
actions	object	yes
transitions	object[]	yes
people	object	yes
changes	object[]	yes	Up to 50 changed decisions, newest first.

ReplayAction

Field	Type	Required	Description
action	string	yes
rule	integer | null	yes

DecisionGraph

A DMN decision requirements graph; node and edge types are DMN’s names.

Field	Type	Required	Description
profile	string	yes	The profile the graph was asked for.
nodes	object[]	yes
edges	object[]	yes

RequiredSnapshot

What the rules read from one required decision, when this decision was made.

Field	Type	Required	Description
decision	string	yes
profile	string	yes
profile_version	integer	yes
action	string	yes
outcome	string	yes	The person’s answer when a review was resolved
reviewed	boolean	yes
read	object	yes	Every value the rules read from it, by path; null = unknown.

HiddenRequired

A required decision of a profile the reader may not see.

Field	Type	Required	Description
decision	null	yes

Decision

Field	Type	Required	Description
decision_id	string	yes
ref	string	no
answers	object	yes	One answer per question, keyed by question name.
action	string	yes	auto, review, or a custom action defined by the profile.
profile	string	yes
profile_version	integer	yes
model	string	yes	The model that answered.
created_at	string	yes	When the decision was made.
rule	integer | null	yes	Index of the policy rule that matched (from 0); null when the default action applied.
facts	Facts	no	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	no	Present (true) only for a test token’s decision, which is not logged.
requires	object	no	For a profile with requires, by name. A required decision of a profile the token may no longer use is hidden.
replaces	string	no	The earlier decision of the same profile, ref and client that this one replaces.
review	object	no	Present when a person checks the decision before it counts (the profile’s people_check).
versions	Versions	no	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.

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.

Field	Type	Required	Description
engine	string	yes
modules	object	yes	Module name to version, for example “@pointsman/github”.

ProfileStats

Field	Type	Required	Description
profile	string	yes
days	integer	yes
since	string	yes	Decisions made at or after this time are counted.
decisions	integer	yes
actions	object	yes	Decisions per action.
reviews	object	yes
corrected	integer	yes	Decisions where a person corrected at least one answer (as in docs/accuracy.sql).

DecisionRecord

Type: see openapi.yaml.

DecisionRecordBase

Field	Type	Required	Description
decision_id	string	yes
created_at	string	yes
client	string	yes	The client whose token made the decision.
ref	string	no
profile	string	yes
profile_version	integer	yes
model	string	yes
action	string	yes
rule	integer | null	yes	Index of the policy rule that matched; null when the default action applied.
answers	object	yes
facts	Facts	no	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	yes	SHA-256 of the state sent to the model (keys sorted).
state		no	The state sent to the model. Only when the profile sets log.store_state.
review	Review	no	Only for decisions whose action a person checks (the profile’s people_check; default review).
requires	object	no	For a profile with requires, by name. A required decision of a profile the reader may not see is hidden.
idempotency_key	string	no	The Idempotency-Key the decision was made with.
replaces	string	no	The earlier decision of the same profile
versions	Versions	no	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	no	Made while a person resolved the decision it would replace; the client got 409 resolved_by_person and it never counts.

Review

Only for decisions whose action a person checks (the profile’s people_check; default review).

Field	Type	Required	Description
status	“pending” | “resolved” | “superseded”	yes	superseded: a newer decision replaced this one while the review was open, or the client that made it closed the review.
resolved_at	string	no
resolved_by	string	no
final_action	string	no
final_answers	FinalAnswers	no

FinalAnswers

Type: object.

CallbackState

Delivery of the final answer to the decision’s callback_url.

Field	Type	Required	Description
status	“pending” | “delivered” | “failed”	yes
attempts	integer	yes
last_error	string	no
next_at	string	no

ResolveRequest

Field	Type	Required	Description
action	string	yes	The final action, e.g. auto; not review.
correct	object	no	Corrected answers by question name (as in feedback). Empty or left out to keep the model’s answers.
by	string	yes
note	string	no

Resolution

Field	Type	Required	Description
decision_id	string	yes
action	string	yes
answers	FinalAnswers	yes
resolved_by	string	yes
resolved_at	string	yes
callback	“pending” | “none”	yes	pending when the final answer will be sent to the callback_url.

ClosedReview

Field	Type	Required	Description
decision_id	string	yes
review	object	yes

FeedbackRequest

Field	Type	Required	Description
correct	object	yes	Corrected values by question name: true/false (noul), an option (choice), a level (score).
by	string	yes	Who made the correction.
note	string	no

Feedback

Field	Type	Required	Description
created_at	string	yes
client	string	yes
by	string	yes
correct	object	yes
note	string	no

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.

Fact

Type: object | object.

Answer

Type: NoulAnswer | ChoiceAnswer | ScoreAnswer.

NoulAnswer

Field	Type	Required	Description
type	“noul”	yes
value	boolean	yes	true when P(yes) >= 0.5
p	Probability	yes
yes	Probability	yes

ChoiceAnswer

Field	Type	Required	Description
type	“choice”	yes
value	string	yes	The most likely option.
p	Probability	yes
probabilities	Probabilities	yes

ScoreAnswer

Field	Type	Required	Description
type	“score”	yes
value	integer	yes	The most likely level
p	Probability	yes
score	number	yes	Probability-weighted level; can fall between levels.
probabilities	Probabilities	yes	Probability per level, keyed by level index.

Probability

Type: number.

Probabilities

Type: object.

ProfileSummary

Field	Type	Required	Description
id	string	yes
version	integer	yes	Latest version.
versions	integer[]	yes
title	BilingualText	yes
description	BilingualText	yes
requires	string[]	no	The profile ids the latest version requires (decision chains, docs/decision-chains.md).

BilingualText

Field	Type	Required	Description
en	string	yes
ja	string	yes

Error

Field	Type	Required	Description
error	object	yes