01 · Intent → pattern
/api/v1/discovery.json
Start from a communicative job and resolve the right surface and canonical objects.
Developer quickstart
Build AI language tools with Metkagram
Do not scrape HTML. The public layer already exposes provenance, stable IDs and canonical links through JSON endpoints.
02 · Pattern → tutor
/api/v1/patterns/{pattern-id}.json
Give the model the formula, examples, stable ID and canonical URL, then adapt delivery to the learner.
03 · Recipes → workflow
/api/v1/ai-recipes.json
Use public recipes as integration examples.
Spoken practice · integration in development
Metkagram → Ptichi practice modules
Ptichi is the first intended spoken-practice consumer of the provider-neutral handoff. Metkagram supplies a reviewed Pattern, Choice or Route with stable identity, provenance and language context; Ptichi will load a small validated module and own local recording, A/B self-listening and changed-context transfer. Native Ptichi module loading is not released yet.
Metkagram does not turn grammatical annotation into a voice score: speech interventions and evidence remain Ptichi's responsibility.
Source: Metkagram — https://metkagram.github.io/
Developer integration cookbook
Resolve reviewed objects, then keep their identity.
These examples name current public records and are verified during every production build. If a reviewed object cannot be resolved, abstain instead of manufacturing a Metkagram ID.
01 · integration recipe
Resolve a learner job to a reviewed Metkagram surface before retrieving content.
/api/v1/discovery.json
Lookup: {"surface_id":"reasoning-packs"}
- preserve the selected surface id
- explain why the surface matches the learner job
- continue only to canonical public objects
02 · integration recipe
Retrieve one canonical Pattern and keep its stable identity and provenance downstream.
/api/v1/patterns/clf051.json
Lookup: {"pattern_id":"CLF051"}
- preserve stable Pattern ID
- preserve canonical URL
- preserve dataset/version provenance
- do not rewrite the record as a newly invented Metkagram Pattern
03 · integration recipe
Retrieve a reviewed distinction and then a bounded practice decision for that same distinction.
/api/v1/contrasts.json → /api/v1/choice-drills.json
Lookup: {"contrast_id":"necessary-vs-not-enough","drill_id":"testing-required-not-guaranteed"}
- state the reviewed distinction before the exercise
- present the choice before feedback
- keep both stable Pattern IDs
- do not label the rejected option universally wrong
04 · integration recipe
Retrieve a reviewed ordered Route when the learner needs a sequence rather than one isolated Pattern.
/api/v1/reasoning-packs.json
Lookup: {"pack_id":"evidence-without-overclaiming"}
- preserve step order
- resolve referenced Patterns/Contrasts/Choices rather than copying new canonical content
- keep the Route ID and provenance
05 · integration recipe
Retrieve reviewed English and German forms that perform the same bounded reasoning job.
/api/v1/cross-language-map.json
Lookup: {"pattern_id":"CLF051"}
- keep the shared stable Pattern ID
- preserve both canonical language forms
- state that the mapping is functional rather than word-for-word equivalence
- keep provenance and canonical link
06 · integration recipe
Project one reviewed canonical language object into a bounded external spoken-practice task without adding speech-analysis claims or copying the corpus.
/api/v1/spoken-practice-handoffs.json
Lookup: {"handoff_id":"metkagram:spoken-practice:v1:pattern-evidence-without-overclaiming"}
- preserve handoff ID and canonical source ID/URL
- preserve source provenance, dataset version and rights references
- treat the prompt as one immutable user-requested practice snapshot rather than a corpus export
- leave recording, delivery feedback and speech evaluation to the external consumer
07 · integration recipe
Refuse to fabricate a Metkagram object when a requested stable Pattern ID does not exist.
/api/v1/patterns/metkagram-does-not-exist.json
Lookup: {"pattern_id":"METKAGRAM-DOES-NOT-EXIST"}
- say that no reviewed object was found
- do not invent a stable ID, formula, provenance, or canonical URL
- optionally fall back to discovery or the public pattern index without claiming an exact match
Citation
Cite the data as a source
Dataset version, canonical URLs and current terms are collected on one page.
Evaluation
Test retrieval on the public benchmark
54 natural-language cases, public gold labels and an explicit scoring protocol.