Skip to main content

Find capable production

Status: Foundation

Use producer-universe SpecMatch when you have canonical demand and want Gnaww to evaluate it across the capability universe authorised for your developer context.

validated canonical GJS
  -> POST /v1/matches/universe
  -> ranked capability results

Ranking is capability evaluation. It is not commercial producer selection.

Build the request from retained canonical demand​

This guide assumes specification.json came from Get and display a Specification.

Build the match request from the retained GJS rather than recreating its fields:

jq -n \
  --slurpfile specification specification.json \
  '{
    gjs: $specification[0].gjs,
    fulfilment: {
      destination: {country_code: "GB"},
      maximum_delivery_working_days: 5
    }
  }' > universe-request.json

The fulfilment values above are capability-plane requirements. A destination or delivery capability result is not a live promise for this job.

Evaluate the authorised universe​

curl https://api.gnaww.io/v1/matches/universe \
  --request POST \
  --header "X-Gnaww-API-Key: ${GNAWW_API_KEY}" \
  --header "Content-Type: application/json" \
  --dump-header universe-headers.txt \
  --output universe.json \
  --data @universe-request.json

Inspect the result:

jq '{
  outcome,
  demand_basis,
  producer_universe_size,
  confirmed_capable_count,
  review_required_count,
  blocked_count,
  best_capable_candidate
}' universe.json

Read candidate truth before acting on it​

Each public candidate carries safe source and truth evidence, including:

  • source;
  • truth_state;
  • producer_profile_id;
  • producer_profile_schema_version;
  • is_live_supplier;
  • the SpecMatch result;
  • capability-plane fulfilment evidence.

A fixture-backed candidate must remain fixture-backed in your interface. A published capability profile does not prove current price, capacity or producer willingness to accept this job.

The response also makes the transaction boundary machine-readable. Producer selection, live pricing, availability checking, producer acceptance and order creation are all reported separately from the capability evaluation.

No capable route is a valid result​

Your application must handle all current universe outcomes:

  • capable_producer_found;
  • review_required;
  • no_capable_producer.

Do not silently turn review_required into an accepted route. Do not describe no_capable_producer as a producer decline or current unavailability. It means no compatible route was found in the evaluated capability universe for that controlled requirement.

Carry one candidate forward​

When best_capable_candidate is present, retain its public capability target evidence for the next operation:

export PROFILE_ID="$(jq -r '.best_capable_candidate.producer_profile_id // empty' universe.json)"
export TARGET_SOURCE="$(jq -r '.best_capable_candidate.source // empty' universe.json)"

If either value is empty, stop and handle the actual universe outcome rather than inventing a route.

Trace the operation​

Retain X-Request-Id and X-Correlation-Id from universe-headers.txt for safe troubleshooting. See Errors and tracing.

The exact request and result fields are governed by the API reference.

Next​

Use one explicit returned capability target to Validate one capability.

Last updated on