Skip to main content

Understand a print requirement

Status: Implemented

Start here when your application has buyer language, structured system input or another incomplete print requirement and needs controlled Gnaww meaning.

source intent
  -> POST /v1/interpret
  -> controlled intent classification
  -> one or many returned Jobs
  -> scoped clarification when required
  -> canonical GJS v0.4 per ready Job

Gnaww does the interpretation and Job decomposition. Your application should preserve the returned controlled meaning and scope rather than adding its own print assumptions.

Direct HTTP​

Set your developer credential first:

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

Then send the intent:

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

Keep interpretation.json as the operation result. The exact response schema is governed by the API reference.

The v0.2 result exposes top-level intent and shared context, then one or more independently producible Jobs in jobs[]. Canonical GJS, Recipe readiness, SpecMatch readiness, unresolved fields and Job questions belong to the relevant Job rather than being duplicated at the top level.

For a known single-Job workflow, inspect the returned Job first and only then extract its GJS:

jq '.jobs[0] | {job_id, status, product_family, questions, gjs}' interpretation.json
jq '.jobs[0].gjs' interpretation.json > gjs.json

Do not use .jobs[0] as an implicit choice when Gnaww returns multiple Jobs. Iterate the returned jobs[] or let the user select the relevant Job using the returned Job identities. The client should not decompose the source again.

Continue clarification​

Questions carry stable public question_id values and an explicit scope. A question can be shared across the interpretation or owned by one Job.

Return answers by question_id to the continuation route:

curl https://api.gnaww.io/v1/interpret/continue \
  --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",
    "answers": [
      {
        "question_id": "<question-id-returned-by-gnaww>",
        "value": "<selected-or-entered-value>"
      }
    ]
  }'

Preserve the returned question identity. Do not convert it into private canonical field paths or infer a different Job scope in the client.

TypeScript / JavaScript SDK​

The official SDK convenience client exposes the same reviewed interpretation operation:

import { GnawwClient } from '@jawwws/gnaww';

const gnaww = new GnawwClient({
  apiKey: process.env.GNAWW_API_KEY!,
  workspaceId: process.env.GNAWW_WORKSPACE_ID,
});

const response = await gnaww.consumeDetailed(
  '500 A5 flyers and 50 embroidered navy T-shirts',
);

console.log(response.data.intent.kind);
for (const job of response.data.jobs) {
  console.log(job.jobId, job.status, job.productFamily, job.gjs);
}
console.log(response.requestId, response.correlationId);

Python SDK​

import os
from gnaww_sdk import GnawwClient

with GnawwClient(
    api_key=os.environ["GNAWW_API_KEY"],
    workspace_id=os.environ.get("GNAWW_WORKSPACE_ID"),
) as gnaww:
    response = gnaww.consume_detailed(
        "500 A5 flyers and 50 embroidered navy T-shirts"
    )

    print(response.data.intent.kind)
    for job in response.data.jobs:
        print(job.job_id, job.status, job.product_family, job.gjs)
    print(response.request_id, response.correlation_id)

PHP SDK​

<?php

use Jawwws\Gnaww\GnawwClient;

$gnaww = new GnawwClient(
    getenv('GNAWW_API_KEY'),
    'https://api.gnaww.io',
    getenv('GNAWW_WORKSPACE_ID') ?: null,
);

$response = $gnaww->consumeDetailed(
    '500 A5 flyers and 50 embroidered navy T-shirts'
);

foreach ($response->data->getJobs() as $job) {
    printf("%s %s\n", $job->getJobId(), $job->getStatus());
}
var_dump($response->requestId, $response->correlationId);

Trace a request​

Gnaww developer responses expose request and correlation identifiers through response headers. Retain them in your application logs when you can do so safely.

For direct HTTP, inspect:

grep -Ei '^(x-request-id|x-correlation-id):' response-headers.txt

When asking for support, provide those identifiers instead of credentials or sensitive payloads. See Errors and tracing.

Next​

When a returned Job is canonical and your workflow needs a durable reference, continue to Get and display a Specification. For multi-Job intent, retain each required canonical Job explicitly rather than turning the interpretation result itself into an Order.

Last updated on