CASE 1.1 surface for visual standards-browser apps

Build against academic standards as a graph.

Use the official CASE 1.1 read model for frameworks, items, associations, support definitions, and CFPackages. Use TimeBack extensions only where a standards browser needs persistence, discovery, safe writes, or external-ID Alignment.

Start with cURL Endpoint reference Data dictionary

1EdTech pass-through TimeBack gap fill Inherited platform contract

CFDocumentframework root

CFItemstandard or competency

CFAssociationtree and graph edge

CFPackagespec-pure import/export

CFDefinitionssubjects, concepts, licenses

Alignmentexternal ID to CFItem

Alignment stays outside CFAssociation and is never emitted inside CFPackage export.

Quickstart

Call the demo tenant in four lines.

CITD-012

Base URL

https://platform3-andymontgomery-9773s-projects.vercel.app/case/1edtech/implementation/api

The implementation deliverable owns this live canonical URL; demo clients mint a tenantId=demo token on this same API.

Demo token mint

POST /dev/mint?tenantId=demo

Public and demo-only. It mints a bearer token scoped to tenantId demo on the same backend as real tenants.

Real tenants

CASE_REVIEWER_JWT

Operators mint real-tenant JWTs out of band. The public API never mints non-demo credentials.

BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/case/1edtech/implementation/api"
TOKEN="$(curl -s -X POST "$BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"

curl -s "$BASE_URL/ims/case/v1p1/CFDocuments?limit=10&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Cold-client rule.

Every example defines BASE_URL before it uses it. BASE_URL is the CASE implementation canonical API; demo clients mint their own token and reviewer or production clients pass an operator-minted JWT.

Mint an owning document for fresh authoring

For fresh-authored content, create the CFDocument first. Its returned identifier is the owning document id reused by every child write. If another surface or recipe asks for document_id, use this exact CASE CFDocument.identifier value.

BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/case/1edtech/implementation/api"
TOKEN="$(curl -s -X POST "$BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"

DOCUMENT_RESPONSE="$(curl -s -X POST "$BASE_URL/ims/case/v1p1/CFDocuments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mint-course-document-001" \
  --data '{
  "identifier": "3f0d4d8c-2d1c-4fd6-98d5-47ad5dfc3d48",
  "uri": "https://standards.example.org/case/cfdocuments/3f0d4d8c-2d1c-4fd6-98d5-47ad5dfc3d48",
  "frameworkType": "CourseCodes",
  "caseVersion": "1.1",
  "creator": "Example Standards Authority",
  "title": "Example Mathematics Standards",
  "lastChangeDateTime": "2026-05-27T12:00:00Z",
  "officialSourceURL": "https://standards.example.org/math",
  "subject": [
    "Mathematics"
  ],
  "language": "eng",
  "version": "2026"
}')"

DOCUMENT_ID="$(printf '%s' "$DOCUMENT_RESPONSE" | jq -r '.CFDocument.identifier')"
printf 'Use document_id=%s on child CFItem/CFAssociation writes.\n' "$DOCUMENT_ID"

Owning-document rule.

Do not let a child CFItem or CFAssociation silently create the document. A child write whose CFDocumentURI.identifier or equivalent document_id cannot resolve to an active same-tenant CFDocument returns case:missing_parent with a document-not-found field error.

Import a package, then link an external lesson

BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/case/1edtech/implementation/api"
TOKEN="$(curl -s -X POST "$BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"

IMPORT_RESPONSE="$(curl -s -X POST "$BASE_URL/ims/case/v1p1/CFPackages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-example-math-standards-001" \
  --data '{
  "CFDocument": {
    "identifier": "3f0d4d8c-2d1c-4fd6-98d5-47ad5dfc3d48",
    "uri": "https://standards.example.org/case/cfdocuments/3f0d4d8c-2d1c-4fd6-98d5-47ad5dfc3d48",
    "frameworkType": "CourseCodes",
    "caseVersion": "1.1",
    "creator": "Example Standards Authority",
    "title": "Example Mathematics Standards",
    "lastChangeDateTime": "2026-05-27T12:00:00Z",
    "officialSourceURL": "https://standards.example.org/math",
    "subject": [
      "Mathematics"
    ],
    "language": "eng",
    "version": "2026"
  },
  "CFItems": [
    {
      "identifier": "7d2f6d3d-65e4-4a25-85f4-e0cc8f841172",
      "uri": "https://standards.example.org/case/items/7d2f6d3d-65e4-4a25-85f4-e0cc8f841172",
      "CFDocumentURI": {
        "title": "Example Mathematics Standards",
        "identifier": "3f0d4d8c-2d1c-4fd6-98d5-47ad5dfc3d48",
        "uri": "https://standards.example.org/case/cfdocuments/3f0d4d8c-2d1c-4fd6-98d5-47ad5dfc3d48"
      },
      "humanCodingScheme": "3.NF.A.1",
      "fullStatement": "Understand a fraction 1/b as the quantity formed by one part when a whole is partitioned into b equal parts.",
      "abbreviatedStatement": "Understand unit fractions.",
      "educationLevel": [
        "03"
      ],
      "listEnumeration": "A",
      "parentIdentifier": "7c928d2d-7d4e-439e-9a49-0c874cc9af62"
    }
  ],
  "CFAssociations": [
    {
      "identifier": "e5b9fb4b-2f2a-4f2f-82e0-ef4774e6f19c",
      "uri": "https://standards.example.org/case/associations/e5b9fb4b-2f2a-4f2f-82e0-ef4774e6f19c",
      "CFDocumentURI": {
        "title": "Example Mathematics Standards",
        "identifier": "3f0d4d8c-2d1c-4fd6-98d5-47ad5dfc3d48",
        "uri": "https://standards.example.org/case/cfdocuments/3f0d4d8c-2d1c-4fd6-98d5-47ad5dfc3d48"
      },
      "originNodeURI": {
        "title": "3.NF.A.1",
        "identifier": "7d2f6d3d-65e4-4a25-85f4-e0cc8f841172",
        "uri": "https://standards.example.org/case/items/7d2f6d3d-65e4-4a25-85f4-e0cc8f841172",
        "targetType": "CASE"
      },
      "destinationNodeURI": {
        "title": "Number and Operations - Fractions",
        "identifier": "7c928d2d-7d4e-439e-9a49-0c874cc9af62",
        "uri": "https://standards.example.org/case/items/7c928d2d-7d4e-439e-9a49-0c874cc9af62",
        "targetType": "CASE"
      },
      "associationType": "isChildOf",
      "sequenceNumber": 1
    }
  ],
  "CFDefinitions": {
    "CFSubjects": [
      {
        "identifier": "22222222-2222-4222-8222-222222222222",
        "uri": "https://standards.example.org/case/subjects/math",
        "title": "Mathematics",
        "hierarchyCode": "MATH",
        "lastChangeDateTime": "2026-05-27T12:00:00Z"
      }
    ]
  }
}')"

DOCUMENT_ID="$(printf '%s' "$IMPORT_RESPONSE" | jq -r '.documentIdentifier')"
curl -s "$BASE_URL/ims/case/v1p1/CFPackages/$DOCUMENT_ID" \
  -H "Authorization: Bearer $TOKEN"

BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/case/1edtech/implementation/api"
TOKEN="$(curl -s -X POST "$BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"

curl -s -X POST "$BASE_URL/ims/case/v1p1/Alignments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: align-fractions-lesson-001" \
  --data '{
  "alignmentId": "align-demo-fractions-lesson-01",
  "externalSystem": "curriculum-vendor-a",
  "externalId": "lesson-fractions-01",
  "cfItemUri": "https://standards.example.org/case/items/7d2f6d3d-65e4-4a25-85f4-e0cc8f841172",
  "label": "Fractions intro lesson",
  "metadata": {
    "sourceUrl": "https://curriculum.example.test/lessons/fractions-01"
  }
}'

curl -s "$BASE_URL/ims/case/v1p1/Alignments?externalSystem=curriculum-vendor-a&externalId=lesson-fractions-01" \
  -H "Authorization: Bearer $TOKEN"

Real-tenant smoke check

BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/case/1edtech/implementation/api"
TOKEN="${CASE_REVIEWER_JWT:?Set CASE_REVIEWER_JWT from the operator-minted reviewer credential}"

curl -s "$BASE_URL/ims/case/v1p1/CFItems?CFDocumentURI=https%3A%2F%2Fstandards.example.org%2Fcase%2Fcfdocuments%2F3f0d4d8c-2d1c-4fd6-98d5-47ad5dfc3d48&limit=25" \
  -H "Authorization: Bearer $TOKEN"

Follow pagination and filter a graph edge list

BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/case/1edtech/implementation/api"
TOKEN="$(curl -s -X POST "$BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"

PAGE_1="$(curl -s "$BASE_URL/ims/case/v1p1/CFItems?CFDocumentURI=https%3A%2F%2Fstandards.example.org%2Fcase%2Fcfdocuments%2F3f0d4d8c-2d1c-4fd6-98d5-47ad5dfc3d48&limit=2&offset=0" \
  -H "Authorization: Bearer $TOKEN")"
NEXT="$(printf '%s' "$PAGE_1" | jq -r '.links.next // empty')"
NEXT_PATH="$(printf '%s' "$NEXT" | sed -E 's#^https?://[^/]+##; s#^/api/#/#')"
[ -n "$NEXT_PATH" ] && curl -s "$BASE_URL$NEXT_PATH" -H "Authorization: Bearer $TOKEN"

Pagination origin rule.

Use links.next for its path and query, then fetch it on the documented BASE_URL. A client must not change hosts while paging through CASE lists.

BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/case/1edtech/implementation/api"
TOKEN="$(curl -s -X POST "$BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"

curl -s "$BASE_URL/ims/case/v1p1/CFAssociations?associationType=isChildOf&originIdentifier=7d2f6d3d-65e4-4a25-85f4-e0cc8f841172&limit=10" \
  -H "Authorization: Bearer $TOKEN"

Exercise one validation error

BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/case/1edtech/implementation/api"
TOKEN="$(curl -s -X POST "$BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"

curl -i -s -X POST "$BASE_URL/ims/case/v1p1/Alignments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invalid-alignment-example-001" \
  --data '{"alignmentId":"align-demo-missing-target","externalSystem":"curriculum-vendor-a","externalId":"lesson-without-cfitem"}'

{
  "type": "https://platform3-andymontgomery-9773s-projects.vercel.app/problems/case/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "code": "case:validation_failed",
  "detail": "Alignment requires cfItemUri or cfItemIdentifier so the external identifier resolves to a CASE item.",
  "requestId": "req_01HZCASEDEMO00000000000001",
  "traceId": "trace_01HZCASEDEMO000000000001",
  "fieldErrors": [
    {
      "field": "cfItemUri",
      "reason": "required_without_cfItemIdentifier"
    },
    {
      "field": "cfItemIdentifier",
      "reason": "required_without_cfItemUri"
    }
  ],
  "rowErrors": []
}

Authentication

JWT tenant routing, CASE scopes, no tenant path prefix.

The token determines tenant, role, and scopes. Do not send X-Timeback-Tenant and do not add /tenants/{tenantId} to CASE routes.

CITD-009

Scopes
Scope	Meaning	Use when	Trace
`case:read`	Read CFDocuments, CFItems, CFAssociations, CFPackage exports, support definitions, and Alignments.	Grant to clients that browse standards, resolve external IDs, follow graph edges, or export packages without mutating CASE rows.	CITD-009-AUTH-SHAPE
`case:write`	Create and edit per-resource CFDocument, CFItem, CFAssociation, and Alignment rows.	Grant to authoring clients that use per-resource POST, PUT, PATCH, or DELETE. Do not rely on it for CFPackage import without case:import.	CITD-009-AUTH-SHAPE
`case:import`	Import CFPackages and run package-level writes.	Grant to package loader jobs that call POST /CFPackages and need atomic package persistence. Pair with case:read for post-import verification.	CITD-009-AUTH-SHAPE
`case:admin`	Administrative override scope for destructive or audit-sensitive CASE operations.	Reserve for audit views, retained tombstones, repair jobs, or policy exceptions that ordinary read/write/import clients must not reach.	CITD-009-AUTH-SHAPE

Credential boundary.

/dev/mint?tenantId=demo rejects non-demo tenantIds. The default demo token carries case:read/write/import; /dev/mint?tenantId=demo&admin=true is the explicit demo-only maintenance token for case:admin cascade cleanup. Real tenants use operator-minted JWTs, which keeps customer data out of the public demo bootstrap path.

Concurrency

Read with `ETag`; write with `If-Match`.

Mutable CFDocument, CFItem, CFAssociation, and Alignment detail routes use If-Match to prevent silent overwrites. A detail read returns the current ETag; send that value on PUT, PATCH, or DELETE. Admin document cascade uses the same rule on DELETE /CFDocuments/{sourcedId}?cascade=true instead of a wildcard validator. After a write, either use the response ETag or re-read the detail route and use the latest GET ETag before the next write.

CITD-007

Validator headers
Header	Where it appears	Meaning	What to do next
`If-Match`	PUT, PATCH, DELETE request	Current validator from the last detail read or write response.	Missing returns `case:precondition_required`; stale returns `case:precondition_failed`.
`ETag`	GET detail and POST create response	Current strong validator for the returned resource.	Use it as `If-Match` for the first PUT, PATCH, or DELETE.
`ETag`	Successful PUT/PATCH response	Current strong validator after the mutation.	Use it as the next `If-Match`; when in doubt, re-read the detail route and use that GET response's `ETag`.

Chained-write rule.

A client that patches the same resource twice must refresh its validator between writes. The portable path is write, GET the detail route again, then send the refreshed ETag as the second If-Match.

BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/case/1edtech/implementation/api"
TOKEN="$(curl -s -X POST "$BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"
ALIGNMENT_ID="align-demo-fractions-lesson-01"

ETAG="$(curl -sD - -o /tmp/case-alignment.json "$BASE_URL/ims/case/v1p1/Alignments/$ALIGNMENT_ID" \
  -H "Authorization: Bearer $TOKEN" | awk 'tolower($1)=="etag:" {print $2}' | tr -d '\r')"

curl -sD /tmp/case-patch.headers -o /tmp/case-patch.json -X PATCH "$BASE_URL/ims/case/v1p1/Alignments/$ALIGNMENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: patch-alignment-demo-001" \
  -H "If-Match: $ETAG" \
  --data '{"label":"Fractions intro lesson, reviewed"}'

NEXT_ETAG="$(curl -sD - -o /tmp/case-alignment-after-patch.json "$BASE_URL/ims/case/v1p1/Alignments/$ALIGNMENT_ID" \
  -H "Authorization: Bearer $TOKEN" | awk 'tolower($1)=="etag:" {print $2}' | tr -d '\r')"
curl -s -X PATCH "$BASE_URL/ims/case/v1p1/Alignments/$ALIGNMENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: patch-alignment-demo-002" \
  -H "If-Match: $NEXT_ETAG" \
  --data '{"label":"Fractions intro lesson, chained"}'

Errors

Typed RFC 7807 Problems with `case:*` codes.

Every error response includes requestId and traceId so a customer can paste evidence into a support issue without exposing package payloads, JWTs, or private standards data. The type URL is owned by the master Platform3 problem catalog and dereferenceable under https://platform3-andymontgomery-9773s-projects.vercel.app/problems/case/*.

CITD-011

{
  "type": "https://platform3-andymontgomery-9773s-projects.vercel.app/problems/case/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "code": "case:validation_failed",
  "detail": "Alignment requires cfItemUri or cfItemIdentifier so the external identifier resolves to a CASE item.",
  "requestId": "req_01HZCASEDEMO00000000000001",
  "traceId": "trace_01HZCASEDEMO000000000001",
  "fieldErrors": [
    {
      "field": "cfItemUri",
      "reason": "required_without_cfItemIdentifier"
    },
    {
      "field": "cfItemIdentifier",
      "reason": "required_without_cfItemUri"
    }
  ],
  "rowErrors": []
}

Problem codes
Code	Meaning	Use when	Trace
`case:validation_failed`	A request body, query parameter, or CASE field violates the dictionary constraints.	Use when the route and parameter names are supported but a submitted value breaks a field type, CHECK, required-field, allowed-value, or JSON-shape rule. Use a sibling code for unsupported query names, missing parents, cycles, or stale ETags.	CITD-011-ERROR-ENVELOPE dictionary
`case:payload_too_large`	HTTP 413: the JSON request body exceeds the CASE API's 4 MiB application limit.	Use when a create, replace, patch, or CFPackage import crosses the request-body limit. The server rejects the request before repository, graph, import, or persistence work.	CITD-011-ERROR-ENVELOPE dictionary
`case:not_found`	The tenant has no active resource for the supplied identifier.	Use after authentication succeeds and the supplied identifier is well-formed, but no active same-tenant row exists. Do not use to hide missing scopes; that is case:forbidden.	CITD-011-ERROR-ENVELOPE dictionary
`case:forbidden`	The JWT is valid but lacks the CASE scope or tenant access required for the route.	Use when the token verifies but its tenantId or scopes do not authorize the attempted read, write, import, or admin action. Do not use for malformed values or absent rows.	CITD-011-ERROR-ENVELOPE dictionary
`case:unsupported_query_parameter`	A list route received a query parameter outside the published query model.	Use when the query string names a parameter this route does not publish at all. If the parameter is supported but the value is malformed, use case:validation_failed.	CITD-011-ERROR-ENVELOPE dictionary
`case:association_cycle`	An isChildOf edge would create a cycle in the active CFItem tree.	Use only for structural isChildOf mutations where walking destination parents reaches the origin item. Missing or cross-document parents use case:missing_parent instead.	CITD-011-ERROR-ENVELOPE dictionary
`case:missing_parent`	A CFItem has no active structural isChildOf parent or references a missing parent.	Use when a CFItem placement omits its one active parent, references no active same-document CFDocument/CFItem, or has duplicate active parents. Use case:association_cycle when the parent exists but creates a loop.	CITD-011-ERROR-ENVELOPE dictionary
`case:idempotency_conflict`	The same Idempotency-Key was reused with different method, route, or request body hash.	Use when the key is syntactically valid and already recorded for this tenant but the replay does not match the stored request fingerprint. Use case:package_import_failed for package row validation errors.	CITD-011-ERROR-ENVELOPE dictionary
`case:precondition_required`	A mutable route required If-Match and the request omitted it.	Use for PUT, PATCH, or DELETE on ETag-protected resources when no If-Match header is present. Use case:precondition_failed when the header is present but stale.	CITD-011-ERROR-ENVELOPE dictionary
`case:precondition_failed`	The supplied If-Match validator no longer matches the current row.	Use when the client supplied If-Match but it differs from the current strong ETag. Use case:precondition_required only for missing validators.	CITD-011-ERROR-ENVELOPE dictionary
`case:package_import_failed`	A CFPackage failed validation or atomic import.	Use when package-level validation, graph validation, or atomic commit fails and rowErrors describe the failing package paths. Use case:validation_failed for ordinary per-resource payload errors.	CITD-011-ERROR-ENVELOPE dictionary
`case:resource_referenced`	HTTP 409: a requested soft-retire/delete would leave active CASE or Alpha Curriculum rows pointing at the retired resource.	Use when DELETE or a raw retired_at update targets an active CFDocument or CFItem that is still referenced by active CFItems, CFAssociations, Alignments, or Alpha extension references. Row errors identify the blocking path; the referencing row must be retired/deleted or repointed first.	CITD-011-ERROR-ENVELOPE dictionary
`case:legacy_kc_read_only`	HTTP 409: a write targeted a retained legacy CASE Knowledge Component or one of the four #707-governed legacy relationship types.	Legacy CASE KC rows remain readable immutable migration evidence after #707. Author new KCs through Curriculum `POST /alpha/curriculum/v1/kcs`; manage `precedes`, `ext:alpha.needs_first`, `replacedBy`, and `exactMatchOf` relationships through the governed Curriculum registry. Other stock CASE association types retain their normal CASE semantics.	Curriculum KC registry dictionary
`case:server_error`	HTTP 500: the CASE API could not complete the documented operation.	Use only for unexpected server failures after request validation and known conflict handling. The response must include requestId and traceId for support correlation and must not expose raw database errors.	CITD-011-ERROR-ENVELOPE dictionary

Data model

The persisted graph behind the API.

These are the customer-facing resources the implementation must store. Every chip links to the field-level dictionary with type, nullability, invalid cases, examples, and ITD provenance.

CITD-003

CASE link shape.

Fields typed as LinkURIDType or LinkGenURIDType use the CASE object form in request bodies and CFPackages. Send { "title", "identifier", "uri" } for LinkURIDType and add "targetType" for LinkGenURIDType; bare URI strings are only used for URI-typed text fields such as Alignment.cfItemUri and query parameters such as CFDocumentURI.

CFDocument

Stores one standards-framework container, such as Common Core State Standards Math 2010. It is the root object a browser lists before loading CFItems.