Client integration kit

Download the versioned DecisioQ Client Kit 7.6.3 for the OpenAPI contract, Postman collection, JSON Schemas, request examples, .NET reference client, runnable sample, and production-readiness guidance.

Authentication

Protected DecisioQ routes require a bearer token issued by identity.vinquery.com. The Decision API and Decision 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

Recommended execution

Most clients only select a decision and provide business data. Omitted technical settings are resolved from the selected decision, an applicable profile, and safe platform fallbacks. The response's top-level configurationUsed object reports each effective value and its source.

{
  "decisionId": "AUTO-FLEET-001",
  "businessData": {
    "vehicles": [
      { "vehicleId": "fleet-101", "lifecycleCost": 41500, "reliabilityScore": 72 },
      { "vehicleId": "fleet-205", "lifecycleCost": 38900, "reliabilityScore": 81 }
    ]
  }
}

Weight determination and ranking are separate. Omit weighting overrides to use Decision Catalog recommended priorities; select weightStrategy: "AHP" with a complete ahp object to derive weights from relative judgments; or provide manualWeights keyed by every authoritative criterionId when your organization already knows its weights. The independent algorithm field selects TOPSIS or WSM ranking.

AHP execution contract

POST https://dde.vinquery.com/api/v1/ahp/generate accepts the existing AhpRequest contract containing criteria and a complete comparisons collection. It returns normalized weights, lambdaMax, consistencyIndex, consistencyRatio, isConsistent, and comparisonsToReview. It uses the same JWT authentication and usage-accounting boundary as other Decision Service operations.

{
  "criteria": ["cost", "quality", "risk"],
  "comparisons": [
    { "criterionA": "cost", "criterionB": "quality", "importance": 3 },
    { "criterionA": "cost", "criterionB": "risk", "importance": 1 },
    { "criterionA": "quality", "criterionB": "risk", "importance": 0.3333333333 }
  ]
}

Request fields

This section defines the API syntax. For the business meaning, distinction, defaults, and combined behavior of these configuration choices, see Profiles and Scenarios in Decision Concepts.

Request context and units

Keep decision IDs, criterion IDs, option IDs, JSON properties, enum values, endpoint paths, profile IDs, and scenario IDs stable. Localize labels and formatting in the consuming application, not in the machine-readable contract.

Unless this API and the selected decision schema explicitly document unit-qualified values, convert measurements to the required canonical unit before submission. Never infer an input unit from locale. Treat the decision definition as authoritative for data type, canonical unit, accepted input units, conversion behavior, and validation.

{
  "requestContext": {
    "correlationId": "client-workflow-123"
  }
}

Currency conversion is separate from measurement conversion. An exchange rate requires a rate source, valuation date, and conversion policy; automatic currency conversion must not be assumed.

Route reference

Decision Catalog

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

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

The Decision 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
      }
    }
  ]
}

Decision Outcome Feedback

POST https://dde.vinquery.com/api/v1/decision-outcomes

After the host workflow knows what action was taken and what happened, submit outcome feedback using the requestId returned by the original successful /api/v1/decide call. DecisioQ verifies that the original execution belongs to the authenticated account. Feedback is reporting evidence only and never changes scoring, weights, profiles, or catalog knowledge automatically.

{
  "originalDecisionRequestId": "8ee2694f-2a93-42e6-9e37-626a3f83b02b",
  "disposition": "Overridden",
  "selectedOptionId": "lot-002",
  "overrideReason": "Post-decision inspection uncovered frame damage on lot-001.",
  "realizedOutcome": "Alternative vehicle sold within 21 days.",
  "realizedValue": {
    "amount": 2450.00,
    "metric": "grossProfit",
    "currency": "CAD"
  },
  "outcomeTimestampUtc": "2026-08-12T15:30:00Z",
  "attributes": { "inventoryChannel": "retail" }
}

Coding examples

const result = await fetch(`${decisionApi}/api/v1/decision-outcomes`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ ...outcome, originalDecisionRequestId: decision.requestId })
});
if (!result.ok) throw new Error(`Outcome ${result.status}: ${await result.text()}`);

using var response = await httpClient.PostAsJsonAsync("api/v1/decision-outcomes", new {
    originalDecisionRequestId = decision.RequestId,
    disposition = "Accepted",
    selectedOptionId = decision.DecisionResult.Winner,
    realizedOutcome = "Vehicle sold within target window.",
    outcomeTimestampUtc = DateTimeOffset.UtcNow
});
response.EnsureSuccessStatusCode();

status, body = send(
    api + "/api/v1/decision-outcomes",
    {**outcome, "originalDecisionRequestId": decision["requestId"]},
    {"Authorization": "Bearer " + token, "Content-Type": "application/json"})
if status >= 400:
    raise RuntimeError(f"Outcome {status}: {body}")

Outcome reporting

GET https://dde.vinquery.com/api/v1/decision-outcomes/summary?fromUtc=2026-08-01T00:00:00Z&toUtc=2026-09-01T00:00:00Z

The optional range is half-open: fromUtc is inclusive and toUtc is exclusive. The response contains totals, acceptance and override rates as decimal fractions, and realized-value groups separated by metric, unit, and currency. Stability remains decision-execution evidence from sensitivity analysis; correlate it with outcome summaries in the customer's analytics layer.

Responses

This page documents response contracts and endpoint-specific errors. For platform-wide status semantics, retry decisions, diagnostics, and operational handling, see HTTP Status Codes and Error Handling.

{
  "service": "decisioq",
  "version": "7.6.3",
  "requestId": "8ee2694f-2a93-42e6-9e37-626a3f83b02b",
  "operation": "Decide",
  "success": true,
  "timestampUtc": "2026-08-02T12:00:00Z",
  "requestContext": {
    "correlationId": "client-workflow-123",
    "decision": {
      "id": "AUTO-AUCT-044",
      "name": "Approve High-Risk Purchase",
      "catalogVersion": "13.9.3"
    }
  },
  "configurationUsed": {
    "weightStrategy": { "value": "Expert", "source": "ExplicitRequest" },
    "rankingAlgorithm": { "value": "TOPSIS", "source": "ExplicitRequest" },
    "profile": { "value": "balanced", "source": "ExplicitRequest" },
    "sensitivity": { "value": false, "source": "PlatformDefault" }
  },
  "decisionReceipt": {
    "schemaVersion": "1.0",
    "executionId": "89df1c15a1b948e8a6e684b367f25610",
    "correlationId": "client-workflow-123",
    "versions": { "decisionId": "AUTO-AUCT-044", "catalogVersion": "13.9.3", "profileId": "balanced", "profileVersion": "2.1.0", "engineVersion": "7.6.3" },
    "normalizedInputs": [], "appliedCriteria": [], "appliedRules": [],
    "excludedCandidates": [], "rankingExplanation": [], "warnings": [],
    "validationFindings": ["Request validation passed.", "Constraint evaluation completed.", "Ranking completed."],
    "executionDurationMs": 4,
    "integrityAlgorithm": "SHA-256",
    "integrityHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "decisionResult": {
    "winner": "lot-001",
    "ranking": [
      { "rank": 1, "optionId": "lot-001", "score": 0.812 },
      { "rank": 2, "optionId": "lot-002", "score": 0.644 }
    ]
  },
  "explanation": {
    "summary": "Controlled High-Margin Purchase provides the strongest overall fit.",
    "whyRecommended": "It offers the best balance across the configured criteria.",
    "keyDrivers": [],
    "tradeoffs": [],
    "competitors": [],
    "sensitivitySummary": "Sensitivity analysis was not included in this response.",
    "scenarioSummary": "The selected scenario was included in the decision context.",
    "risks": [],
    "nextSteps": [],
    "assumptions": []
  }
}

The standard response omits catalog narrative and diagnostics, but always includes decisionReceipt. Receipt arrays in this shortened example are populated in production responses. Store the complete receipt unchanged; changing any receipt evidence changes its SHA-256 hash. To request safe expansions, add "responseOptions": { "includeDecisionMetadata": true, "includeDiagnostics": true } to either supported request shape. AI prompt metadata is never returned.

Data Preparation Guide metadata

GET /api/decisioq/data-preparation-metadata returns the centralized Integration Platform preparation rules used by the documentation renderer. The renderer combines those rules with the selected decision detail from Decision Catalog; it does not modify decision knowledge or execute transformations.

Each generated criterion guide includes Decision Catalog business meaning, unit, and direction together with typical source fields, illustrative data preparation, validation guidance, assumptions, example raw business data, and an example prepared criteria mode.