Compatibility Matrix

The compatibility matrix says which of your programs chain well together and which must never follow each other. Each pair of programs has a rule per direction:

Direction	Meaning
FOR	the rule applies when the program comes before the related one
TO	the rule applies when the program comes after the related one

A rule is PREFERRED (a best match), INCOMPATIBLE, or absent (neutral). The two directions are independent: a FOR rule never implies a TO rule the other way round.

These endpoints are for DMC keys. The matrix belongs to the organization your key acts for; a key with several organizations sends the X-Organization-Id header. Anything outside that organization answers 404, not 403.

For the full request and response schemas, see the complete API Reference.

Nothing changes until you confirm

Every change goes through a review:

1. You send a proposal (or upload a workbook). It becomes an import.
2. KOOB analyzes the import in the background and lists the cells it would change.
3. You show that list to the person who owns the matrix.
4. Only a confirmation with the import's latest reviewToken writes the rules.

If someone edits the matrix between the review and the confirmation, the import goes back to ready with a new reviewToken and new changes. Review it again and confirm again; KOOB never applies a stale review.

What	Endpoint
Read the matrix	GET /api/v3/experience-compatibility-matrix
The AI prompt	GET /api/v3/experience-compatibility-matrix/prompt
Propose changes	POST /api/v3/experience-compatibility-matrix/proposals
Upload a workbook	POST .../imports, POST .../imports/{id}/chunks, POST .../imports/{id}/analysis
Review an import	GET .../imports/{id}, GET .../imports/{id}/changes, GET .../imports/{id}/errors
Confirm an import	POST .../imports/{id}/confirmation
Download the workbook	GET .../imports/{id}/workbook-chunks

Read the matrix

GET /api/v3/experience-compatibility-matrix lists your programs, 20 per page by default, each with its explicit rules:

{
  "data": [
    {
      "id": "101",
      "name": "Hanoi highlights",
      "rules": [
        { "direction": "FOR", "value": "PREFERRED", "relatedExperienceId": "102" },
        { "direction": "TO", "value": "INCOMPATIBLE", "relatedExperienceId": "103" }
      ]
    }
  ],
  "meta": {
    "currentPage": 1,
    "lastPage": 1,
    "perPage": 20,
    "total": 1,
    "baseline": "5d41402abc4b2a76b9719d911017c592…"
  }
}

meta.baseline identifies the state of the matrix. Every page of one read carries the same value; if it changes while you page, start again. Send it back with your proposal.

A pair can't be both PREFERRED and INCOMPATIBLE. If older data breaks that rule, the read (and any import or proposal) answers 409 COMPATIBILITY_RULES_CONFLICT, with the pairs in details.pairs. Correct them in KOOB first.

A group account owns no programs: name one of its organizations in the X-Organization-Id header, or the read answers 400 ORGANIZATION_REQUIRED.

Propose changes

POST /api/v3/experience-compatibility-matrix/proposals answers 202 with the new import. The body states what the user asked for and exactly which cells it may touch:

Field	What it holds
baseline	meta.baseline of the matrix you read
criteria	the user's request, as you understood it
directions	FOR, TO or both
scopeExperienceIds	the source programs in scope
scopePairs	every { experienceId, relatedExperienceId, direction } cell the user authorized
changes	each cell to change: its pair, currentValue, proposedValue and a reason
exceptions	cells the user protected
ambiguities	cells you are unsure about, each with a reason

KOOB refuses a proposal (400 INVALID_COMPATIBILITY_PROPOSAL) that changes a cell outside scopePairs, changes the same cell twice, or touches an exception or an ambiguity. A currentValue that no longer matches KOOB, or a stale baseline, answers 409 COMPATIBILITY_BASELINE_STALE: read the matrix again.

GET .../prompt returns the instructions an AI client should follow to build a proposal from a request in plain language.

Upload a workbook

To send an edited Excel workbook without a file upload:

1. POST .../imports with { "filename": "compatibilities.xlsx" }. The import is uploading.
2. POST .../imports/{id}/chunks with { "offset": 0, "base64": "…" }, at most 262,144 decoded bytes per chunk. offset must equal the import's uploadedBytes; otherwise 409 UPLOAD_OFFSET_MISMATCH.
3. POST .../imports/{id}/analysis with { "uploadedBytes": 18234 }, the complete file size. KOOB starts the analysis once every byte has arrived.

The workbook must be a complete export: both sheets (compatibilities for and compatibilities to), every program on both axes, the Experience ID column and row, X on the diagonal, and only PREFERRED, INCOMPATIBLE or empty cells. At most 20 MB.

Review and confirm

Poll GET .../imports/{id} until status is ready or invalid:

Status	Meaning
uploading	waiting for chunks
analyzing	KOOB is checking the workbook or proposal
ready	valid; nothing is applied yet
invalid	see GET .../imports/{id}/errors
applying	confirmed, being written
completed	the rules are live
failed	see failure

GET .../imports/{id}/changes lists every cell the import would change, with its current and proposed value and, for a proposal, your reason. Show them to the user.

When the user approves, POST .../imports/{id}/confirmation with { "confirmed": true, "reviewToken": "…" }. A missing, old or already used token answers 409 COMPATIBILITY_REVIEW_STALE: read the import again.

Download the workbook

GET .../imports/{id}/workbook-chunks?offset=0 returns the complete XLSX as base64 byte ranges of up to 262,144 bytes. Decode each range and append it until nextOffset equals totalBytes.