DecisioQ API Reference

Authentication

Protected DecisioQ routes require a bearer token issued by identity.vinquery.com. The Decision API and Knowledge Catalog validate incoming bearer tokens; the Decision API does not create, sign, or issue JWT tokens.

The hosted identity endpoint is https://identity.vinquery.com/connect/token.

Request a token with clientId, clientSecret, and audience. Send the returned token as Authorization: Bearer {token} when calling protected DecisioQ routes.

{
  "clientId": "{clientId}",
  "clientSecret": "{clientSecret}",
  "audience": "vinquery:api:decisioq"
}

The API Consumer must be enabled, allowed to request the DecisioQ audience, and linked to a DecisioQ account. The Decision API uses that account link for usage accounting.

Public hosts

Service	Base URL	Purpose
Identity	`https://identity.vinquery.com`	Issues JWT tokens for API Consumers.
Knowledge Catalog	`https://dks.vinquery.com`	Returns catalog discovery and decision metadata.
Decision API	`https://dde.vinquery.com`	Validates and executes decision requests.

Request fields

Field	Required	Description
`decisionId`	Yes	Stable catalog decision identifier, for example `AUTO-AUCT-044`.
`profileId`	No	Decision-specific profile returned by decision detail metadata. Omit to use the decision default.
`scenarioId`	No	Decision-specific scenario returned by decision detail metadata.
`requestContext`	No	Correlation, locale, unit, currency, time zone, and jurisdiction metadata.
`options`	Yes for Prepared Decision Input	Two or more candidate options. Each option contains `optionId`, optional `name`, and criterion `values`.
`businessData`	Yes for business-data input	Domain payload prepared by an Industry Profile. Do not send both `options` and duplicate candidate arrays unless the API contract explicitly requires both.

Request context and units

API identifiers use stable American-English names. Presentation metadata can be supplied in requestContext. Measured values must include a unit when the selected decision or Industry Profile requires measurement normalization.

{
  "requestContext": {
    "correlationId": "client-workflow-123",
    "locale": "en-CA",
    "measurementSystem": "metric",
    "currency": "CAD",
    "timeZone": "America/Toronto",
    "jurisdiction": { "countryCode": "CA", "regionCode": "ON" }
  }
}

Error	Meaning
`MISSING_MEASUREMENT_UNIT`	A measured value was submitted without a required unit.
`UNSUPPORTED_MEASUREMENT_UNIT`	The supplied unit is not accepted for that measurement type.
`INCOMPATIBLE_MEASUREMENT_UNIT`	The unit does not match the expected measurement dimension.

Route reference

Operation	Method	Route	Purpose
Decision API Health	GET	https://dde.vinquery.com/health	Anonymous readiness check for the Decision API.
Preview Decision	POST	https://dde.vinquery.com/api/v1/validate	Validate business data and selected decision input without producing a recommendation.
Execute Decision	POST	https://dde.vinquery.com/api/v1/decide	Execute using either Prepared Decision Input or businessData.
Catalog Health	GET	https://dks.vinquery.com/health	Anonymous readiness check for the Knowledge Catalog.
Catalog Sectors	GET	https://dks.vinquery.com/decisioncatalog	Load sectors, categories, decision counts, category metadata, and overview text.
Decision Detail	GET	https://dks.vinquery.com/decisioncatalog/decisions/AUTO-AUCT-006	Load decision metadata, overview, criteria, profiles, scenarios, validation rules, and constraints.
Category Decisions	GET	https://dks.vinquery.com/decisioncatalog/sectors/{sectorCode}/categories/{categoryCode}/decisions	Load decisions for one selected sector/category.

Knowledge Catalog

GET https://dks.vinquery.com/decisioncatalog

GET https://dks.vinquery.com/decisioncatalog/decisions/AUTO-AUCT-006

The Knowledge Catalog is the source of decision metadata. Except for /health, catalog routes require Authorization: Bearer {token}.

{
  "catalogId": "DKR-AUTO-RUNTIME-001",
  "industry": "Automotive",
  "sectorCount": 13,
  "decisionCount": 1051,
  "sectors": [
    {
      "sectorCode": "AUTO-AUCT",
      "sector": "Auto Auctions",
      "decisionCount": 49,
      "categories": [
        {
          "categoryCode": "AUTO-AUCT-COMPLIANCE-RISK",
          "category": "Compliance & Risk",
          "decisionCount": 4
        }
      ]
    }
  ]
}

Preview Decision Validation

POST https://dde.vinquery.com/api/v1/validate

Returns validation status without producing a recommendation. Validation uses the same catalog metadata, required fields, candidate-count rules, numeric ranges, measurement rules, and hard constraints used by execution.

{
  "decisionId": "AUTO-AUCT-044",
  "requestContext": { "correlationId": "client-workflow-123" },
  "options": [
    {
      "optionId": "lot-001",
      "values": {
        "expected_profit_margin": 5200,
        "risk_exposure": 12,
        "title_confidence": 90,
        "repair_uncertainty": 12,
        "management_priority": 90
      }
    },
    {
      "optionId": "lot-002",
      "values": {
        "expected_profit_margin": 4700,
        "risk_exposure": 22,
        "title_confidence": 82,
        "repair_uncertainty": 22,
        "management_priority": 82
      }
    }
  ]
}

Execute Decision

POST https://dde.vinquery.com/api/v1/decide

Validates input, applies catalog-defined hard constraints, scores eligible options, and returns the recommendation and ranked result. Execution is deterministic; explanatory text does not override the ranking or recommendation.

{
  "decisionId": "AUTO-AUCT-044",
  "profileId": "balanced",
  "scenarioId": "standard",
  "requestContext": { "correlationId": "client-workflow-123" },
  "options": [
    {
      "optionId": "lot-001",
      "values": {
        "expected_profit_margin": 5200,
        "risk_exposure": 12,
        "title_confidence": 90,
        "repair_uncertainty": 12,
        "management_priority": 90
      }
    },
    {
      "optionId": "lot-002",
      "values": {
        "expected_profit_margin": 4700,
        "risk_exposure": 22,
        "title_confidence": 82,
        "repair_uncertainty": 22,
        "management_priority": 82
      }
    }
  ]
}

Responses

Field	Description
`requestId`	Server-generated request identifier.
`correlationId`	Client-supplied correlation identifier when present.
`decisionId`	Executed catalog decision.
`recommendation`	Recommended option summary.
`rankedResults`	Ranked eligible options and scores.
`constraintOutcomes`	Eligible and excluded candidate outcomes when hard constraints apply.
`warnings`	Non-fatal validation or execution warnings.
`executionTrace`	Technical trace metadata when returned by the API.

{
  "requestId": "8ee2694f-2a93-42e6-9e37-626a3f83b02b",
  "correlationId": "client-workflow-123",
  "decisionId": "AUTO-AUCT-044",
  "recommendation": {
    "optionId": "lot-001",
    "name": "Controlled High-Margin Purchase"
  },
  "rankedResults": [
    { "rank": 1, "optionId": "lot-001", "score": 0.812 },
    { "rank": 2, "optionId": "lot-002", "score": 0.644 }
  ],
  "constraintOutcomes": {
    "eligibleCount": 2,
    "excludedCount": 0
  }
}