# Response Samples

These samples are aligned to the tracked 2026-07-15 Content Alpha contract. Item list/detail examples include the exact 27-key `publicItem` projection, including nullable conditional slices. Other examples may use the explicit `jq` projection shown above them. For current live values, run the calls in `worked-example.md`; the surface is the answer key.

Do not turn these samples into a private enum table or fixture database. They are examples of what the API returns. The legacy `customerWebsite` response links currently lead to a withdrawn status surface; use `dataDictionary` and `architecture` as the current documentation authorities.

## Descriptor

```bash
curl -fsS "$CONTENT_BASE_URL" -H "Authorization: Bearer $CONTENT_TOKEN" \
  | jq '{module, surface, status, docs: (.docs | {architecture, dataDictionary, customerWebsite}), quickstart: (.quickstart | {mintDemoToken, listContent, studentView}), allowedFilters, allowedValues: (.allowedValues | {content_kind, assessment_component_role, expected_xp_band, content_reference_relationship_kind, catalog_facet_key})}'
```

```json
{
  "module": "content",
  "surface": "alpha",
  "status": "ok",
  "docs": {
    "architecture": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/architecture",
    "dataDictionary": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/data_dictionary",
    "customerWebsite": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/customer_website"
  },
  "quickstart": {
    "mintDemoToken": "POST /content/alpha/implementation/api/dev/mint?tenantId=demo",
    "listContent": "GET /content/alpha/implementation/api/tenants/{tenantId}/alpha/content/items",
    "studentView": "GET /content/alpha/implementation/api/tenants/{tenantId}/alpha/content/items/{contentId}/student-view"
  },
  "allowedFilters": [
    "content_kind",
    "subtype",
    "dok",
    "assessment_role",
    "subject_id",
    "alpha_subject_id",
    "target_grade_id",
    "curriculum_node_id",
    "usage_scope",
    "test_type",
    "is_mastery_gate",
    "source_system",
    "source_record_id",
    "source_activity_ref",
    "facet",
    "modifiedSince",
    "cursor",
    "limit",
    "subject",
    "grade_band",
    "language",
    "accessibility_profile",
    "rights_license",
    "provenance",
    "quality_rating",
    "kc_refs",
    "standards_framework_refs",
    "expected_xp_band",
    "modality"
  ],
  "allowedValues": {
    "content_kind": ["question", "test", "test_spec", "test_bank", "article", "video", "audio", "image", "interactive", "media_asset", "external_link", "script"],
    "assessment_component_role": ["test", "section", "part", "question", "question_ref", "distractor", "rubric", "preauthored_feedback"],
    "expected_xp_band": ["0_to_10", "10_to_20", "20_to_45", "45_plus"],
    "content_reference_relationship_kind": ["embeds", "depends_on", "transcript_for", "caption_for", "thumbnail_for", "source_file_for", "source_script_for", "alternative_form_of", "bank_member", "related_material"],
    "catalog_facet_key": ["subject", "grade_band", "language", "accessibility_profile", "rights_license", "provenance", "quality_rating", "kc_refs", "standards_framework_refs", "content_kind", "expected_xp_band", "modality"]
  }
}
```

## List Assessment Components

```bash
curl -fsS "$CONTENT_BASE_URL/tenants/demo/alpha/content/items/58612cab-9c46-426c-8c20-0e9f19c807c5/assessment-components?component_role=rubric" \
  -H "Authorization: Bearer $CONTENT_TOKEN"
```

```json
{
  "data": [
    {
      "assessment_component_id": "0e732fd3-2df8-5d08-b436-fc5b20fe1b0c",
      "content_id": "58612cab-9c46-426c-8c20-0e9f19c807c5",
      "version_id": "efcf3561-3a66-4825-9588-e792ef20c312",
      "parent_assessment_component_id": "e74ec8f3-1825-5c6d-b60f-b2bbef3f4c87",
      "component_role": "rubric",
      "ordinal": 2,
      "element_name": "qti-rubric-block",
      "qti_identifier": "short-response-rubric",
      "response_identifier": null,
      "outcome_identifier": null,
      "feedback_identifier": null,
      "show_hide": null,
      "display_text": "Full credit requires a correct equation step and solution.",
      "source_trace": {
        "element": "qti-rubric-block",
        "schemaFile": "imsqti_itemv3p0p1_v1p0.xsd"
      }
    },
    {
      "assessment_component_id": "5e86f3ed-6ff7-5cae-af04-d016d2fd9f99",
      "content_id": "58612cab-9c46-426c-8c20-0e9f19c807c5",
      "version_id": "efcf3561-3a66-4825-9588-e792ef20c312",
      "parent_assessment_component_id": "e74ec8f3-1825-5c6d-b60f-b2bbef3f4c87",
      "component_role": "preauthored_feedback",
      "ordinal": 3,
      "element_name": "qti-modal-feedback",
      "qti_identifier": "correct",
      "response_identifier": null,
      "outcome_identifier": null,
      "feedback_identifier": "correct",
      "show_hide": "show",
      "display_text": "Correct. Substituting x = 6 balances both sides.",
      "source_trace": {
        "element": "qti-modal-feedback",
        "schemaFile": "imsqti_itemv3p0p1_v1p0.xsd"
      }
    },
    {
      "assessment_component_id": "409a3db9-85df-56ac-95f3-e0116d176d44",
      "content_id": "58612cab-9c46-426c-8c20-0e9f19c807c5",
      "version_id": "efcf3561-3a66-4825-9588-e792ef20c312",
      "parent_assessment_component_id": "e74ec8f3-1825-5c6d-b60f-b2bbef3f4c87",
      "component_role": "preauthored_feedback",
      "ordinal": 4,
      "element_name": "qti-modal-feedback",
      "qti_identifier": "incorrect",
      "response_identifier": null,
      "outcome_identifier": null,
      "feedback_identifier": "incorrect",
      "show_hide": "show",
      "display_text": "Check the inverse operation: subtract 5, then divide by 2.",
      "source_trace": {
        "element": "qti-modal-feedback",
        "schemaFile": "imsqti_itemv3p0p1_v1p0.xsd"
      }
    }
  ],
  "nextCursor": null
}
```

## List Answer Keys

Teacher or authoring tools may read answer keys directly only with `read:answer_key`:

```bash
curl -fsS "$CONTENT_BASE_URL/tenants/demo/alpha/content/items/58612cab-9c46-426c-8c20-0e9f19c807c5/answer-keys" \
  -H "Authorization: Bearer $CONTENT_TOKEN"
```

```json
{
  "data": [
    {
      "answer_slot_id": "0c6f5271-9d9e-4df1-8d5d-2ad59dacde66",
      "correct_response": { "values": ["choiceA"] },
      "mapping": {
        "defaultValue": 0,
        "mapEntries": [{ "mapKey": "choiceA", "mappedValue": 1 }]
      },
      "required_scope": "read:answer_key"
    }
  ],
  "nextCursor": null
}
```

## List Articles By KC Discovery Facet

```bash
curl -fsS "$CONTENT_BASE_URL/tenants/demo/alpha/content/items?content_kind=article&facet=kc_refs:case:math:7.ee.b.4&limit=3" \
  -H "Authorization: Bearer $CONTENT_TOKEN"
```

```json
{
  "data": [
    {
      "content_id": "f71f3b0a-e271-40ea-b990-89940f371012",
      "workspace_id": "0d4ce2f4-1c42-4f3c-9f0d-03fb7f5271d3",
      "content_kind": "article",
      "subtype": null,
      "dok": null,
      "title": "Integration article 1d0b6d39 revised",
      "language": "en-US",
      "source_identifier": null,
      "subject_id": "math",
      "target_grade_id": "7",
      "expected_xp": 12,
      "usage_scope": "practice_eligible",
      "assessment_role": null,
      "test_type": null,
      "is_mastery_gate": null,
      "test_family_id": null,
      "phonics_constraint": null,
      "constraint_set_id": null,
      "policy_version": null,
      "latest_version_id": "5a9c6b6d-c955-4fec-8b73-a3ced5fe22c6",
      "source_system": "alpha_content",
      "source_record_id": null,
      "source_activity_ref": null,
      "status": "draft",
      "created_at": "2026-06-04T09:44:25.292Z",
      "updated_at": "2026-06-04T09:44:26.072Z",
      "retired_at": null
    }
  ],
  "nextCursor": "Mw",
  "hasMore": true,
  "links": {
    "dataDictionary": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/data_dictionary",
    "customerWebsite": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/customer_website#endpoint-list-content-items"
  }
}
```

## Detail

```json
{
  "content_id": "f71f3b0a-e271-40ea-b990-89940f371012",
  "workspace_id": "0d4ce2f4-1c42-4f3c-9f0d-03fb7f5271d3",
  "content_kind": "article",
  "subtype": null,
  "dok": null,
  "title": "Integration article 1d0b6d39 revised",
  "language": "en-US",
  "source_identifier": null,
  "subject_id": "math",
  "target_grade_id": "7",
  "expected_xp": 12,
  "usage_scope": "practice_eligible",
  "assessment_role": null,
  "test_type": null,
  "is_mastery_gate": null,
  "test_family_id": null,
  "phonics_constraint": null,
  "constraint_set_id": null,
  "policy_version": null,
  "latest_version_id": "5a9c6b6d-c955-4fec-8b73-a3ced5fe22c6",
  "source_system": "alpha_content",
  "source_record_id": null,
  "source_activity_ref": null,
  "status": "draft",
  "created_at": "2026-06-04T09:44:25.292Z",
  "updated_at": "2026-06-04T09:44:26.072Z",
  "retired_at": null
}
```

## Student View

```json
{
  "version_id": "5a9c6b6d-c955-4fec-8b73-a3ced5fe22c6",
  "student_view": {
    "kind": "article",
    "title": "Integration article 1d0b6d39",
    "blocks": [
      {"text": "Two-step equations", "type": "heading"},
      {"text": "Solve by balancing both sides. Content stores the blank material only.", "type": "paragraph"}
    ]
  },
  "etag": "W/\"content:f71f3b0a:v1:98c2461145df\"",
  "answerSlots": [],
  "answerKeysIncluded": false,
  "links": {
    "dataDictionary": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/data_dictionary#object-content-version",
    "customerWebsite": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/customer_website#endpoint-get-student-view"
  }
}
```

## Media

```json
{
  "data": [
    {
      "media_id": "4a343d51-d65b-4425-bfa2-293211c45251",
      "content_id": "f71f3b0a-e271-40ea-b990-89940f371012",
      "version_id": "5a9c6b6d-c955-4fec-8b73-a3ced5fe22c6",
      "media_kind": "transcript",
      "media_type": "text/plain",
      "byte_length": 104,
      "content_hash": null,
      "storage_path": null,
      "delivery_url": "/content/alpha/implementation/api/tenants/demo/alpha/content/items/f71f3b0a/media/4a343d51",
      "metadata": {"title": "Worked solution transcript", "language": "en-US"},
      "created_at": "2026-06-04T09:44:25.629Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```

## Content References

```json
{
  "data": [
    {
      "content_reference_id": "67b4ddfb-5369-4fd8-a0ef-e139e3638b01",
      "parent_content_id": "f71f3b0a-e271-40ea-b990-89940f371012",
      "parent_content_kind": "article",
      "referenced_content_id": "9a49cb4d-7840-42d4-a8a6-512f19dbe98ca",
      "referenced_content_kind": "image",
      "relationship_kind": "embeds",
      "display_order": 1
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```

The referenced content is still a separate flat Content row. Call the referenced row's detail, student-view, media, trust, or effectiveness endpoints when needed; do not nest it into the parent row.

## Catalog Facets

List the named facet registry:

```bash
curl -fsS "$CONTENT_BASE_URL/tenants/demo/alpha/content/catalog-facets?grain=content_item" \
  -H "Authorization: Bearer $CONTENT_TOKEN"
```

```json
{
  "data": [
    {
      "facet_key": "expected_xp_band",
      "label": "Expected XP band",
      "value_type": "enum",
      "grain": "content_item",
      "allowed_values": [
        {"value": "0_to_10", "label": "0 to 10 XP"},
        {"value": "10_to_20", "label": "10 to 20 XP"},
        {"value": "20_to_45", "label": "20 to 45 XP"},
        {"value": "45_plus", "label": "45+ XP"}
      ],
      "status": "active"
    },
    {
      "facet_key": "quality_rating",
      "label": "Quality rating",
      "value_type": "enum",
      "grain": "content_item",
      "allowed_values": [
        {"value": "unreviewed", "label": "Unreviewed"},
        {"value": "approved", "label": "Approved"},
        {"value": "preferred", "label": "Preferred"},
        {"value": "needs_review", "label": "Needs review"}
      ],
      "status": "active"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```

List assignments for one item:

```json
{
  "data": [
    {
      "facet_assignment_id": "1fd04ddf-f5e7-4fd5-b170-cf0345711f39",
      "content_id": "f71f3b0a-e271-40ea-b990-89940f371012",
      "version_id": null,
      "media_id": null,
      "facet_key": "expected_xp_band",
      "facet_value": "10_to_20",
      "provenance": {"policy": "alpha.policy.content.expected_xp_band.v1"}
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```

## Weighted KC Tags

```json
{
  "data": [
    {
      "tenant_id": "demo",
      "content_id": "f71f3b0a-e271-40ea-b990-89940f371012",
      "kc_id": "001c6d5d-b370-559a-93d4-3483845ad2f2",
      "weight": 0.8,
      "is_primary": true,
      "provenance": "teacher-review",
      "confidence": 0.95,
      "created_at": "2026-07-16T13:30:00.000Z",
      "updated_at": "2026-07-16T13:30:00.000Z",
      "retired_at": null
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```

## Bounded Graph Write Rejection

When a graph-bearing write would require a 4,097th joined question/KC fact, the complete typed Problem shape is:

```json
{
  "type": "https://platform.timeback.com/problems/content/invalid-test-bank-member-contract",
  "title": "Fix the test-bank membership graph",
  "status": 409,
  "code": "content.invalid_test_bank_member_contract",
  "detail": "The test-bank graph exceeds the supported 4,096-question/KC-fact safety limit and must be split before it can be validated or served.",
  "requestId": "req_0bd65755-a79e-479d-a1bd-a717986774ec",
  "traceId": "trace_8abf4ce2-3e4d-4059-91dd-cc8fc1965cf6",
  "fieldErrors": [
    {
      "name": "form_graph",
      "reason": "Observed at least 4097 question/KC-fact; the supported maximum is 4096."
    }
  ]
}
```

The same code uses `fieldErrors.name=bank_members` for a 1,025th active member and `form_graph` for a 1,025th affected bank. The rejected write changes no graph row, item timestamp/ETag, or fresh idempotency claim. Retire or split the graph before retrying; completed HTTP replay is mutation- and budget-free after ledger arbitration.

## Effectiveness

```json
{
  "content_id": "f71f3b0a-e271-40ea-b990-89940f371012",
  "validated_by_count": 0,
  "failed_by_count": 0,
  "effectiveness_rate": null,
  "freshness_status": "insufficient_data",
  "last_recomputed_at": null,
  "provenance": {
    "policy": "alpha.policy.content_effectiveness.v1",
    "resultCount": 0,
    "sourceModule": "results"
  },
  "links": {
    "dataDictionary": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/data_dictionary#object-content-effectiveness",
    "customerWebsite": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/customer_website#endpoint-get-effectiveness"
  }
}
```

## Trust

```json
{
  "content_id": "f71f3b0a-e271-40ea-b990-89940f371012",
  "trust_status": "unknown",
  "evidence_url": null,
  "checked_at": null,
  "problem_code": null,
  "links": {
    "dataDictionary": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/data_dictionary#object-content-trust-evidence",
    "customerWebsite": "https://platform3-andymontgomery-9773s-projects.vercel.app/content/alpha/customer_website#endpoint-get-trust"
  }
}
```

## Common Cartridge Export

The current `round_trip_check` field is export/package inspection metadata. Even when its status is `passed`, the runtime has not re-imported the package or proven lossless equivalence.

```bash
curl -fsS -X POST "$CONTENT_BASE_URL/tenants/demo/alpha/content/exports/common-cartridge" \
  -H "Authorization: Bearer $CONTENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"course_component_id":"cur_comp_math_7_linear_equations","curriculum_node_id":"case:math:7.ee.b.4","format":"common_cartridge_1_3","round_trip_check":true}'
```

```json
{
  "export_id": "cc_export_2c42e8f2",
  "format": "common_cartridge_1_3",
  "source_course_component_id": "cur_comp_math_7_linear_equations",
  "download_url": "/content/alpha/implementation/api/tenants/demo/alpha/content/exports/common-cartridge/cc_export_2c42e8f2/download?state=...",
  "content_refs": [
    {
      "content_id": "f71f3b0a-e271-40ea-b990-89940f371012",
      "content_kind": "article",
      "title": "Integration article 1d0b6d39 revised"
    }
  ],
  "round_trip_check": {
    "status": "passed",
    "translation_logic_used": false,
    "manifest_resource_count": 3,
    "zip_entry_count": 8,
    "package_byte_length": 1234
  }
}
```

Use `download_url` exactly as returned when the user needs the package bytes. Do not generate or inspect the package as part of a normal app workflow, and do not present `round_trip_check` as reimport proof.

## Exact-Version Release Eligibility

The read uses ordinary `read:content`. Content derives the answer from the
owning item lifecycle and item-level revocation; `trust_status=failed` is the
single revocation lever (owner ruling #2534), the server-owned QC receipt for
the exact immutable version is provenance, and no producer append is required.

```json
{
  "content_id": "58612cab-9c46-426c-8c20-0e9f19c807c5",
  "content_version_id": "efcf3561-3a66-4825-9588-e792ef20c312",
  "content_kind": "question",
  "usage_scope": "practice_eligible",
  "trust_status": "trusted",
  "serveable": true,
  "release_eligible": true,
  "problem_code": null
}
```

For draft, retired, failed/unknown/missing item trust, or a missing exact-version
receipt, the route returns `409 content.version_not_serveable`.

## Policies

```json
{
  "data": [
    {
      "policy_key": "alpha.policy.content_effectiveness.freshness_window_days",
      "value_json": {"days": 1},
      "policy_version": "2026-06-03.1",
      "updated_at": "2026-06-03T18:17:08.745Z"
    },
    {
      "policy_key": "alpha.policy.content_effectiveness.minimum_eligible_results",
      "value_json": {"minimum": 10},
      "policy_version": "2026-06-03.1",
      "updated_at": "2026-06-03T18:17:08.745Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```

## Problem JSON

Unsupported filter:

```json
{
  "type": "https://platform.timeback.com/problems/content/unsupported-filter",
  "title": "Use a documented filter",
  "status": 400,
  "code": "content.unsupported_filter",
  "detail": "Unsupported query parameter: title.",
  "requestId": "req_d181dfd0-1092-4939-ad24-79d5da2f684e",
  "traceId": "trace_2a23bbfe-e37a-4e11-9faf-4013f81c539a",
  "fieldErrors": [
    {
      "name": "title",
      "reason": "Use only the typed filters documented for this endpoint."
    }
  ]
}
```

Authentication required:

```json
{
  "type": "https://platform.timeback.com/problems/content/authentication-required",
  "title": "Sign in with a trusted token",
  "status": 401,
  "code": "content.authentication_required",
  "detail": "Bearer [redacted] is required.",
  "requestId": "req_d181dfd0-1092-4939-ad24-79d5da2f684e",
  "traceId": "trace_2a23bbfe-e37a-4e11-9faf-4013f81c539a",
  "fieldErrors": []
}
```