Recipes

This page is the "show me end to end" companion to the rest of the Build section. Each recipe is a complete journey — a real task an editor, rights manager, or product owner actually does — written on two tracks at once. The outer track is the business action, in plain English, the way it happens in a console or a workflow. The inner track, tucked into a collapsible beneath each step, is the exact Public API call that carries it out, so an integrator or an AI agent can reproduce the same journey without guessing at endpoints.

Read the top line of each step and you have the story. Open the collapsible and you have the request. Everything on the API track is copy-paste shaped against the real spec: the base is https://api.packtpub.services, the prefix is /v0/, every request carries a WorkOS-issued JWT in the Authorization header, and the Tenant is read from the token's tenant_id claim — there is no API key and no tenant header. IDs in the examples use readable slugs (wk_ml_go, res_ml_go_ch3) so you can follow one thing across the whole journey.

One rule sits under every recipe and is worth stating once: content must belong to a Work under an active Contract before it can be used in a Product, in distribution, or on any AI surface. The rights that govern content are held once on the Work, projected onto each Resource, and revalidated at the point of use. Most of what these recipes do is, underneath, arranging content so that this one rule resolves the way you want.

flowchart LR
    R1["Recipe 1<br/>Manuscript → Product"] --> R2["Recipe 2<br/>Re-sync after edits"]
    R1 --> R3["Recipe 3<br/>Compile a course"]
    R1 --> R4["Recipe 4<br/>RAG with rights"]

The four recipes build on one another. Recipe 1 gets a manuscript into the estate and sold as a Product. Recipe 2 keeps it current after the author edits the source. Recipe 3 reuses several published books to compile a new course. Recipe 4 puts the finished content behind an AI assistant — with the rights check that every AI surface must make.

Recipe 1 — From manuscript to published Product

An editor has a book's chapters as Word documents and wants the book live as a Product. The shape of the journey is: register the intellectual property as a Work, put it under a Contract, ingest the chapters as Resources, snapshot the reviewed versions, compose a Product from them, and publish.

flowchart LR
    W["Create Work<br/>wk_ml_go"] --> C["Attach Contract<br/>ctr_chandra_2026"]
    C --> I["Ingest chapters<br/>res_ml_go_ch1…"]
    I --> S["Snapshot versions<br/>ver_…"]
    S --> P["Compose Product<br/>prod_ml_go_book"]
    P --> PUB["Publish"]

Step 1 — Register the Work

Create the Work first, so every chapter you upload lands under it — and under its rights — immediately. The Work is the thing the book is, independent of any file.

POST /v0/content-lake/works HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json
Idempotency-Key: wk-ml-go-create-01

{
  "title": "Machine Learning with Go",
  "slug": "ml-go"
}

Step 2 — Put the Work under a Contract

Select or create the Contract that carries all of the rights and royalty terms, with this Work in its scope. When the contract goes ACTIVE, the platform resolves the Work's rights and projects them onto everything under it. Until then the content can be ingested and worked on, but it is not usable.

{
  "detail-type": "platform.contract.v1.state_changed",
  "source": "packt/svc-contracts",
  "detail": {
    "contract_id": "ctr_chandra_2026",
    "work_ids": ["wk_ml_go"],
    "from_status": "CONTRACT_STATUS_DRAFT",
    "to_status": "CONTRACT_STATUS_ACTIVE"
  }
}

Step 3 — Ingest each chapter into the Work

Upload each chapter. The ingestion pipeline archives the file, converts it to the Packt Content Format (PCF), splits it, and writes it as a Resource of type DOCUMENT under the Work — with a Source record and an INGESTION Activity attached for provenance.

POST /v0/content-lake/resources HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json
Idempotency-Key: res-ml-go-ch3-create-01

{
  "type": "DOCUMENT",
  "title": "Chapter 3 — Feature Engineering",
  "slug": "ml-go-ch3",
  "work_id": "wk_ml_go",
  "source_id": "src_ml_go_manuscript"
}

Step 4 — Snapshot the reviewed versions

Editing happens in the source tool; the Content Lake holds explicit snapshots, not a live copy. The working state is latest. When a chapter has been reviewed and you want a stable, citable version, take a snapshot — that is the version a Product will pin to.

POST /v0/content-lake/resources/res_ml_go_ch3/versions HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json

{
  "label": "Reviewed for first edition"
}

Step 5 — Compose the Product

In Product Management, create a Product that references the Work. Because rights live on the Work, the Product inherits one coherent answer to what it may be sold as and where. Build the composition — the ordered tree of chapters — pinning each content node to the reviewed version from Step 4.

POST /v0/products HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json

{
  "type": "Book",
  "title": "Machine Learning with Go",
  "language": "en",
  "work_id": "wk_ml_go",
  "concurrent": false,
  "composition": [
    { "kind": "FRONT_MATTER" },
    {
      "kind": "CONTENT",
      "resource_id": "res_ml_go_ch3",
      "version": "ver_ml_go_ch3_r1"
    }
  ],
  "manifestations": [
    {
      "class": "EBOOK",
      "formats": [{ "format": "EPUB", "source": "RENDERED" }]
    }
  ]
}

Step 6 — Publish

Move the Product through its lifecycle — DRAFT → REVIEW → APPROVED → PUBLISHED. Each transition is a verb; publishing emits platform.products.product.v1.published, which Distribution and search indexers consume.

POST /v0/products/prod_ml_go_book:transition HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json

{ "action": "submitted" }

Recipe 2 — Re-sync after the author edits the source

The author fixes a broken code sample in chapter 3. Nothing needs to be re-created: the Content Lake keeps the content identity stable across the edit, snapshots the new state, and latest-tracking Products update themselves. This is the errata path — a same-content correction, recorded as a REVISION, never a new Work.

flowchart LR
    E["Author edits<br/>in Word / Google Docs"] --> SN["Connector snapshots<br/>new version"]
    SN --> A["REVISION Activity<br/>supersedes prior version"]
    A --> EV["resource.v1.updated<br/>change_type: RESOURCE_CHANGE_TYPE_VERSION"]
    EV --> L["Latest-tracking<br/>Products re-point"]
    EV --> PIN["Pinned Products<br/>notified, not mutated"]

Step 1 — Edit in the native tool

The Content Lake is not the editing surface. The author corrects the chapter in Word Online or Google Docs. The source connector snapshots it on its next pass, producing a new Resource version — the block-level hashing means only the blocks that actually changed are stored and re-processed.

GET /v0/content-lake/resources/res_ml_go_ch3?fields=id,version,hash,hash_content HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Step 2 — Snapshot the corrected version

Once the connector has pulled the edit into latest, snapshot it so there is a stable, citable corrected version.

POST /v0/content-lake/resources/res_ml_go_ch3/versions HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json

{
  "label": "Errata — corrected chapter 3 code samples"
}

Step 3 — Latest-tracking Products update themselves

The Content Lake emits platform.content-lake.resource.v1.updated with change_type: RESOURCE_CHANGE_TYPE_VERSION. Product Management translates that into a product-scoped platform.products.content.v1.updated and re-points every node tracking latest. Pinned Products keep producing identical output — that is what pinning is for.

GET /v0/products?references_resource=res_ml_go_ch3&page_size=50 HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Step 4 — Re-pin the ones you want to move

For a Product pinned to the old version, re-pinning is a deliberate editorial action — update the node's version specifier to the corrected version. It never happens automatically.

PATCH /v0/products/prod_ml_go_book HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json

{
  "composition": [
    {
      "kind": "CONTENT",
      "resource_id": "res_ml_go_ch3",
      "version": "ver_ml_go_ch3_r2"
    }
  ]
}

Recipe 3 — Compile a derived course from several books

A commissioning editor assembles a course from chapters of three published books. Building a course is a derivation question, never a manifestation grant — the result is a new Work whose provenance points back at its sources through USED edges, and whose royalty split is computable from the ContentUnits it reused.

flowchart TD
    B1["Book A chapter<br/>cu_go_conc_ch5"] --> COMP["COMPILATION Activity"]
    B2["Book B chapter<br/>cu_k8s_net_ch2"] --> COMP
    B3["Book C chapter<br/>cu_ml_go_ch3"] --> COMP
    COMP -->|generated| CW["Course Work<br/>wk_go_platform_course"]
    COMP -->|USED edges| B1
    COMP -->|USED edges| B2
    COMP -->|USED edges| B3

Step 1 — Check DERIVE on every source Work

Before any content moves, run a qualified rights check per source: may the platform derive from this Work? A source whose contract prohibits derivation is swapped out here, not discovered later.

GET /v0/content-lake/works/wk_ml_go?fields=id,rights HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "id": "wk_ml_go",
  "rights": {
    "usable": true,
    "usage_terms": [
      { "usage_type": "DERIVE", "status": "PERMITTED" }
    ],
    "basis": ["ctr_chandra_2026@v3"]
  }
}

Step 2 — Excerpt the reused chapters as ContentUnits

Each reused chapter segment is registered as a ContentUnit (cu_) via an EXCERPTION Activity — same Work as its source. The ContentUnit is the unit the royalty split is later computed from.

POST /v0/content-lake/activities HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json

{
  "type": "EXCERPTION",
  "used": [
    { "resource_id": "res_ml_go_ch3", "version": "ver_ml_go_ch3_r2" }
  ],
  "generated": [{ "content_unit_id": "cu_ml_go_ch3" }],
  "work_relationship": "SAME_WORK",
  "parameters": { "word_count": 4200, "purpose": "course-lesson" }
}

Step 3 — Compile into a new course Work

A COMPILATION Activity used the ContentUnits and generated the course Work and its Resource. The USED edge set is exactly what makes the multi-source royalty split computable.

POST /v0/content-lake/activities HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json

{
  "type": "COMPILATION",
  "used": [
    { "content_unit_id": "cu_go_conc_ch5" },
    { "content_unit_id": "cu_k8s_net_ch2" },
    { "content_unit_id": "cu_ml_go_ch3" }
  ],
  "generated": [
    { "work_id": "wk_go_platform_course" },
    { "resource_id": "res_go_platform_course_m1" }
  ],
  "work_relationship": "NEW_WORK",
  "royalty_flow": "NET_SHARE",
  "rights_basis": [
    "ctr_chandra_2026@v3",
    "ctr_okonkwo_2025@v2",
    "ctr_singh_2026@v1"
  ]
}

Step 4 — Paper the course Work and build the Course Product

The new course Work is a first-class Work: it needs its own Contract before anything built on it can ship. Once papered, compose a Course Product from it — a SCORM_PACKAGE manifestation, an ONLINE manifestation, or both.

POST /v0/products HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json

{
  "type": "Course",
  "title": "Building Cloud-Native Platforms in Go",
  "language": "en",
  "work_id": "wk_go_platform_course",
  "manifestations": [
    {
      "class": "SCORM_PACKAGE",
      "formats": [
        {
          "format": "SCORM",
          "source": "RENDERED",
          "packaging": {
            "schema": "SCORM_2004_4E",
            "organization": {
              "modules_from": "MODULE",
              "scos_from": "LESSON"
            },
            "sequencing": "LINEAR",
            "completion": { "rule": "ALL_SCOS", "mastery_score": 0.8 }
          }
        }
      ]
    }
  ]
}

Recipe 4 — RAG with rights checking

A developer builds an AI assistant that answers from Content Lake content. The pattern is: search for relevant Resources, read the PCF with its Knowledge Graph entities for context, and — before a single passage reaches the model — confirm the content permits AI retrieval. That last check is not optional: some publishers prohibit AI use, and resolving rights at retrieval time is how the platform respects those terms.

flowchart LR
    Q["User question"] --> SR["Search<br/>rights predicate applied"]
    SR --> RD["Read PCF + entities<br/>top results"]
    RD --> RC["Confirm AI_RETRIEVAL<br/>PERMITTED"]
    RC -->|permitted| M["Serve to the model<br/>with attribution"]
    RC -->|prohibited| X["Exclude"]

Step 1 — Search with a rights predicate

Run a hybrid search — lexical, semantic, and Knowledge Graph blended — and add the AI_RETRIEVAL PERMITTED predicate to the same query, so prohibited content never enters the candidate set. Combine it with tag filters to scope the search: tag-filtered queries are fast regardless of result-set size.

POST /v0/content-lake/search HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json

{
  "query": "feature engineering for tabular data in Go",
  "search_mode": "hybrid",
  "filters": {
    "tags": ["topic/machine-learning"],
    "rights": { "usage_type": "AI_RETRIEVAL", "status": "PERMITTED" }
  },
  "page_size": 10
}

Step 2 — Read the top results as PCF with entities

For the top-ranked Resources, read the PCF. The abridged read returns entity ids only, which keeps payloads small — good for fitting many Resources into a context window. Add ?fields=* (or ?fields=…,entities) to inline the full entity overlay when the model needs the context. A common pattern: abridged for the initial search, complete for only the top few.

GET /v0/content-lake/resources/res_ml_go_ch3 HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Accept: application/x-ndjson

GET /v0/content-lake/resources/res_ml_go_ch3?fields=*,entities HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Accept: application/json

Step 3 — Confirm AI_RETRIEVAL before serving to the model

The search predicate scopes the candidate set, but the authoritative check is at the point of use, against the contract versions pinned in each Resource's rights_basis. Confirm AI_RETRIEVAL is PERMITTED for each passage before it reaches the model.

GET /v0/content-lake/resources/res_ml_go_ch3?fields=id,rights HTTP/1.1
Host: api.packtpub.services
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "id": "res_ml_go_ch3",
  "rights": {
    "usable": true,
    "resolved": [
      {
        "usage_type": "AI_RETRIEVAL",
        "status": "PERMITTED",
        "rights_basis": ["ctr_chandra_2026@v3"]
      }
    ]
  }
}

Step 4 — Serve with attribution

Attribution is a first-class concern. When the assistant answers from a passage, surface the source — the author, the title, a link back. The Content Lake provides the provenance; your application is responsible for showing it. Without attribution or click-through, authors lose the reason to publish, which is the whole point the platform protects.

Related pages

• Public API — the endpoints, field masks, pagination, and error shape every recipe above builds on.
• Authentication — how the WorkOS JWT and its tenant_id claim authorise each call.
• Events & webhooks — the events these recipes emit and how to consume them, including CloudEvents at the egress.
• No-code & AI tools — running these journeys from Zapier, n8n, or an LLM agent without writing a service.
• Content Lake — Example flows — the same journeys told business-first, without the API track.
• Explorer — Chapter I — the whole platform, visualised chapter by chapter.