DecisioQ API 1.0 Documentation

DecisioQ is a decision intelligence platform for business applications that need to choose, rank, justify, and audit operational decisions. The current platform combines a secured Knowledge Catalog, governed Industry Profiles, deterministic Decision Execution, catalog-defined validation and constraints, and a business-friendly explanation layer.

The current user and integration workflow is:

1. Load the Knowledge Catalog.
2. Select Sector, Category, Decision, Profile, and Scenario.
3. Review the Selection Overview and criterion guidance.
4. Enter Business Data for the candidate cases.
5. Preview Decision input for validation and preparation when needed.
6. Execute Decision and review the deterministic recommendation.
7. Read the Explanation of Decision Result and, when needed, developer diagnostics.

Many applications frequently need to answer questions such as:

• Which supplier should we select?
• Which vehicle should be purchased?
• Which claim should be prioritized?
• Which carrier provides the best value?
• Which customer application should be approved?
• Which inventory item should be replenished first?

While these decisions appear straightforward, they usually involve competing criteria such as cost, risk, quality, availability, compliance, customer impact, and long-term value.

By externalizing decision logic into DecisioQ, organizations can keep decisions consistent and auditable across multiple products without embedding custom scoring rules, validation rules, or eligibility constraints in every application.

The DecisioQ Knowledge Catalog is the authoritative discovery source for available business decisions. It is secured by JWT authentication and organized around business language rather than internal engine concepts.

The current discovery flow is:

1. Sector - the automotive business area, such as Auto Auctions or Auto Insurance.
2. Category - a real catalog category within the selected sector.
3. Decision - a named decision type returned by the catalog; the dropdown displays the Decision Name while retaining the decision ID internally.
4. Profile - a governed Industry Profile that supplies decision-specific weights, defaults, and business context.
5. Scenario - a named operating situation used to load realistic sample Business Data and assumptions.

Decision detail responses include overview metadata for decisions, criteria, profiles, scenarios, validation rules, and catalog-defined hard constraints. This allows the Business Decision Studio and client applications to explain the selected sector, category, decision, and individual data fields without hard-coded page text.

Current catalog endpoints include:

• GET https://dks.vinquery.com/decisioncatalog - lightweight sector and category discovery.
• GET https://dks.vinquery.com/decisioncatalog/sectors/{sectorCode}/categories/{categoryCode}/decisions - decision list for a category when decisions are not embedded.
• GET https://dks.vinquery.com/decisioncatalog/decisions/AUTO-AUCT-006 - complete decision metadata, criteria, profiles, scenarios, validation, constraints, and overview content.

Profiles and Scenarios let one catalog decision support more than one business posture without creating duplicate decisions or changing candidate Business Data.

For example, AUTO-AUCT-006 uses the same auction-house candidate cases while allowing profiles such as balanced, cost_focused, quality_focused, and risk_averse. The selected profile changes how criteria are weighted. The selected scenario, such as standard, limited_budget, high_demand, or risk_control, identifies the operating context and can affect scoring when the catalog scenario defines computational adjustments.

{
  "decisionId": "AUTO-AUCT-006",
  "profileId": "quality_focused",
  "scenarioId": "high_demand",
  "options": [
    {
      "optionId": "option-1",
      "name": "Premium Metro Auction",
      "values": {
        "vehicle_availability_score": 86,
        "buyer_fee_level": 720,
        "average_vehicle_quality": 92,
        "distance_to_facility": 18,
        "auction_reputation_score": 94,
        "title_processing_speed": 88
      }
    }
  ]
}

Client applications should always populate Profile and Scenario dropdowns from the selected decision detail response. If a profile or scenario is not returned by the catalog for that decision, do not hard-code or submit it.

Decision execution is deterministic. The engine validates Business Data, enforces catalog-defined validation rules, applies hard constraints, normalizes criteria, applies weights, scores eligible candidate cases, ranks them, and returns the recommendation.

The current public integration language is:

• Industry Profile - the business configuration selected for the decision.
• Business Data - the customer or application payload being evaluated.
• Prepared Decision Input - the validated and normalized request ready for execution.
• Decision Preview - validation and preparation without final execution.
• Decision Execution - the final deterministic decision run.
• Decision Result - the ranked result, recommendation, scores, confidence, and supporting details.

A typical result contains:

• Recommended option
• Ranked candidate cases
• Eligible and excluded candidate outcomes when hard constraints apply
• Scores and confidence
• Key drivers and criterion contributions
• Warnings, assumptions, and validation messages
• Execution trace metadata for authorized technical users

Explanation of Decision Result is rendered after the deterministic result. It helps business users understand the outcome but does not overwrite rankings, scores, eligibility decisions, or recommendations.

DecisioQ uses a server-side integration model. Browser demos call same-origin proxy handlers so credentials and tokens are never exposed directly in client-side JavaScript.

Production service hosts are:

• https://identity.vinquery.com - issues JWT access tokens.
• https://dks.vinquery.com - serves the secured Decision Knowledge Catalog.
• https://dde.vinquery.com - validates and executes Decision API requests.

The production pattern is:

1. A trusted server or gateway requests a JWT token from https://identity.vinquery.com/connect/token.
2. The client sends Business Data to the trusted server or gateway.
3. The server calls the Knowledge Catalog and Decision API with Authorization: Bearer YOUR_JWT_TOKEN.
4. The Decision API propagates the bearer token when it retrieves authoritative decision metadata from the Knowledge Catalog.
5. The Decision API validates the token, loads the current catalog definition, applies validation and constraints, and executes the selected decision.
6. The response is returned to the client with business results and optional technical diagnostics.

The token request includes the target audience. For Decision API calls, use vinquery:api:decisioq.

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

The API Consumer must be enabled, allowed to request this audience, and linked to a DecisioQ account for decision execution usage accounting.

The Decision API validates incoming bearer tokens. Token issuance is handled by the identity service, not by the Decision API.

All API traffic uses HTTPS and JSON request/response bodies.

The current public API surface is centered on identity, discovery, validation, and execution.

Endpoint	Purpose	Typical User
POST https://identity.vinquery.com/connect/token	Request a JWT access token for the required audience.	Trusted client gateways and server-side integrations.
GET https://dks.vinquery.com/health	Check Knowledge Catalog readiness.	Operations and integrators.
GET https://dks.vinquery.com/decisioncatalog	Load available sectors and categories.	Business applications and demos.
GET https://dks.vinquery.com/decisioncatalog/decisions/AUTO-AUCT-006	Load full decision metadata, criteria, profiles, scenarios, validation, constraints, and overview content.	Business Decision Studio and client integrations.
GET https://dde.vinquery.com/health	Check Decision API readiness.	Operations and integrators.
POST https://dde.vinquery.com/api/v1/validate	Preview and validate the selected decision input before producing a recommendation.	Client gateways and onboarding flows.
POST https://dde.vinquery.com/api/v1/decide	Execute either Prepared Decision Input by decision ID or business-data requests that include a businessData object.	Production integrations, catalog-driven demos, and business-data integrations.

Preview Decision

Preview validates the selected decision input without completing the final recommendation workflow. Use it before execution when users are editing Business Data, building integrations, or checking that Prepared Decision Input matches the selected catalog decision.

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

Execute Decision

Execution validates the same input and runs the selected decision once. The deterministic Decision Result is authoritative.

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

The response can include:

• Recommended option
• Ranked options
• Constraint outcomes for eligible and excluded candidates
• Confidence score
• Decision summary and result metrics
• Explanation of Decision Result
• Warnings and validation messages
• Execution trace metadata for technical review

Business Decision Studio

The Business Decision Studio demonstrates the same workflow in a business-facing UI: choose the decision, understand it, enter case information, evaluate candidate cases, run the decision, and review the recommendation and explanation.

Status Code	Description
200	Successful request
400	Invalid request, invalid Business Data, or validation failure.
401	Missing, invalid, or expired bearer token.
403	Authenticated account is not authorized for the requested decision or operation.
404	Decision, catalog item, profile, scenario, or endpoint not found.
429	Rate limit exceeded if throttling is enabled.
500	Internal processing, configuration, or upstream service error.

DecisioQ keeps API identifiers stable and uses American-English technical names for decision IDs, criterion IDs, JSON fields, and endpoints. User-facing labels may be localized separately for Canada, the United States, and future markets.

Decision calculations use canonical metric values internally. Client applications may submit metric or US customary measurements when the unit is explicit. The Integration Platform normalizes supported units before the Decision Execution service scores the request.

Input	Accepted Examples	Canonical Processing
Distance	km, mi	Converted to kilometres for evaluation.
Weight	kg, lb	Converted to kilograms for evaluation.
Temperature	degC, degF	Converted to Celsius for evaluation.
Pressure	kPa, psi	Converted to kilopascals for evaluation.
Speed and fuel economy	km/h, mph, l/100km, mpg-us	Converted to canonical metric forms for evaluation.

Measurement normalization trace metadata preserves the submitted value and unit, the canonical value and unit, and the conversion used. Presentation settings such as locale, measurementSystem, currency, timeZone, and jurisdiction affect display and interpretation context; they do not change deterministic scoring.

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

To maximize decision quality and integration reliability:

• Load decisions from the Knowledge Catalog instead of hard-coding IDs in user interfaces.
• Display Decision Name to users while retaining decision ID internally for integration.
• Use the selected Industry Profile and Scenario to prepare realistic Business Data.
• Always include explicit units when submitting measurements that may be metric or US customary.
• Preview Decision input before execution when users are editing or importing data.
• Treat the deterministic Decision Result as authoritative.
• Use Explanation of Decision Result to help users understand the recommendation.
• Keep credentials and bearer tokens on trusted servers or server-side proxies.
• Collapse execution trace and diagnostics by default in business-facing screens.
• Include the required token audience when requesting access tokens.
• Link API Consumers to DecisioQ accounts before executing decisions.
• Respect catalog validation ranges, including percentage and score fields that must remain within 0 to 100.
• Treat hard constraints as eligibility rules; excluded candidates do not participate in ranking.
• Store correlation IDs and decision IDs needed for audit and support.

By following these practices, applications can leverage DecisioQ as a reliable, transparent, and scalable decision intelligence platform.