Skip to main content

Start with Gnaww

Gnaww is Jawwws' print intelligence product, powered by SpecMatch™. It accepts incomplete, inconsistent or system-originated print intent, turns it into controlled print requirements, understands producer capability and compares demand with compatible production possibilities.

Developer preview

The public developer surface is currently the reviewed gnaww-developer-v0.1 contract. Its interpretation operation uses the job-centric gnaww.interpretation_result v0.2 envelope. Official TypeScript, Python and PHP SDKs and the Gnaww CLI are installable. Developer API credentials are still provisioned through controlled access while the self-service developer journey is being completed.

The developer flow​

incomplete, inconsistent or system-originated print intent
  -> Gnaww interpretation
  -> one or many independently producible Jobs
  -> shared or Job-scoped clarification when required
  -> canonical Gnaww Job Specification per ready Job
  -> durable Specification resource when your workflow needs a stable demand reference
  -> Recipe and Recipe ID when one physical definition is exact and eligible
  -> SpecMatch™
  -> compatible producer capability

A Job is one independently producible product. One interpretation can therefore return one Job or several Jobs without becoming an Order. Variants, Components and Operations remain inside the Job where they belong.

A Gnaww Job Specification is the complete canonical demand and run model for one Job. A Specification resource is an explicitly retained immutable GJS with a stable specification_id. A Recipe is the exact physical manufacturing definition inside the GJS. Recipe ID is the deterministic permanent identity of an eligible exact Recipe. SpecMatch™ compares controlled demand and run constraints with producer capability.

Specification ID and Recipe ID are deliberately different. A Specification identifies one retained demand resource. Recipe ID identifies physical manufacturing equivalence.

Capability matching is not live commerce. It does not by itself confirm a price, current availability, producer acceptance, a quote or an order.

1. Configure your developer credential​

Authenticated developer operations use a scoped Gnaww API credential.

export GNAWW_API_KEY="<developer-api-key>"

If your credential is scoped to a workspace, also set:

export GNAWW_WORKSPACE_ID="<workspace-id>"

Keep credentials out of source control, tickets and chat. See Authentication for the current preview boundary.

2. Make your first request​

The preferred messy-intent boundary is POST /v1/interpret.

curl https://api.gnaww.io/v1/interpret \
  --request POST \
  --header "X-Gnaww-API-Key: ${GNAWW_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "source": {
      "type": "natural_language",
      "raw_text": "500 A5 flyers and 50 embroidered navy T-shirts"
    },
    "gjs_version": "0.4"
  }'

The result exposes intent, shared_context, jobs[], scoped questions[] and the interpretation truth boundary. A simple request uses the same envelope with one entry in jobs[]. Multi-product intent can return several Jobs in source order.

Gnaww may return canonical_ready, review_required, needs_review or failed. An incomplete Job is not silently completed just to produce a Recipe ID, and a multi-Job interpretation is not an Order.

When you receive completed canonical demand and need a durable integration reference, retain the required returned Job GJS through POST /v1/specifications. Interpretation itself remains side-effect free with respect to public Specification persistence.

3. Continue the build journey​

The Build with Gnaww guides connect the reviewed operations into practical tasks:

  1. Understand a print requirement.
  2. Get and display a Specification.
  3. Find capable production.
  4. Validate one capability.
  5. See the truthful production handoff boundary and production tracking direction, both currently Planned.

The guides show the workflow. The API reference remains the field-level request and response schema authority.

4. Choose your integration surface​

The same reviewed HTTP contract is available through:

Print interpretation, semantic Job decomposition, canonical demand retention, Recipe canonicalisation and SpecMatch intelligence stay in Gnaww. SDKs, CLIs and adapters expose the returned meaning but do not reimplement it.

Last updated on