API change notice for integration teams

Use this workflow after an API change has technical approval and before consumers need to act. It gives platform engineers, developer relations teams and technical programme managers one notice format, one review path and a clear readiness record for every consumer.

The output is a published change notice plus a consumer tracker. Do not use it to decide whether an API design should be approved. That decision comes first.

1. Open a change record

Create one change record in your existing release tracker. Use its identifier in the notice subject line, document title and consumer tracker.

Collect these inputs before asking the model to draft anything:

• The approved API specification diff, including request and response examples.
• The list of affected endpoints, methods and fields.
• The deployment plan, with test environment availability date, production change date and rollback condition.
• The consumer inventory: team name, service, owner, support channel and current integration method.
• The migration guide or engineering notes, if they exist.
• The named technical owner, release coordinator and on-call contact.

Separate facts from open questions. If the specification does not state whether an omitted field is accepted, record Open question: behaviour for omitted field. Do not let the model infer an answer from surrounding text.

2. Build the consumer impact table

Make a row for each known consumer, not just each endpoint. One consumer may use several endpoints and need a different migration path from another consumer.

Use these fields in the tracker:

Field	What to record
Consumer	Team and service name
Affected interface	Endpoint, method, field or authentication flow used
Breaking behaviour	Exact old behaviour and exact new behaviour
Required action	Code, configuration or operational change
Test date	Date the consumer can test, plus deadline for confirmation
Support contact	Named team and monitored contact route
Readiness decision	Ready, ready with condition, blocked, or not assessed
Evidence	Test reference, owner confirmation or reason for decision

Do not use affected as the readiness decision. It says nothing about whether the consumer has completed its work.

For a breaking change, write the behaviour in paired form:

• Before: POST /orders accepts a request without customer_reference.
• After: POST /orders rejects that request unless customer_reference is present and valid.
• Consumer action: Send customer_reference on every new order request and update request validation tests.

This wording prevents a common failure: saying a field is “now required” without naming the request that fails or the action the consumer must take.

3. Draft the notice from a fixed brief

Give the model one bounded drafting task. Include the approved facts, the consumer impact table and the required output structure. If the model's available behaviour or limits affect your process, check the current xAI documentation overview before relying on it.

Use a prompt in this form:

Draft an API change notice for integration teams.

Use only the facts below. Mark missing facts as [OPEN QUESTION].
Do not add endpoint behaviour, dates, support routes or compatibility claims.

Change record: [ID]
Summary: [approved summary]
Affected endpoints and fields: [list]
Before and after behaviour: [facts]
Migration actions: [facts]
Test environment dates: [dates]
Production change date: [date]
Rollback condition: [condition]
Support contacts: [contacts]
Consumer tracker: [rows]

Structure the notice as:
1. What changes
2. Who is affected
3. Breaking behaviour
4. Migration actions
5. Test and production dates
6. Support and escalation
7. Consumer readiness table

For each consumer, end with one of: Ready, Ready with condition, Blocked, Not assessed.
Keep technical terms from the supplied material unchanged.

Ask for a notice suitable for the channel you will use, such as an internal release bulletin or a direct message to integration owners. Do not ask the model to “make it reassuring”. Clear uncertainty is more useful than calm-sounding uncertainty.

4. Check every statement against the change record

Review the draft with the technical owner and release coordinator. Read it line by line against the specification diff and deployment plan.

Check these points in order:

1. Match every endpoint, method, field and status code to the approved change record.
2. Confirm each breaking statement gives an old behaviour, a new behaviour and a consumer action.
3. Check that dates have a purpose: test environment available, confirmation deadline, production change or rollback decision point.
4. Confirm that the support contact is active for the stated period and that escalation ownership is named.
5. Compare the readiness table with the tracker. Every listed consumer needs one decision and evidence.
6. Remove vague claims such as no impact expected unless a named owner has supplied test evidence.

A useful final check is to give the draft, the approved facts and the tracker to a reviewer who did not write it. Ask them to identify unsupported claims, missing actions and unresolved consumers. Correct the source tracker first, then regenerate or edit the notice.

5. Publish the notice and request a decision

Publish one canonical notice location. Link directly to the migration guide and the consumer tracker if your internal process permits it. Send the same change record identifier in every message so replies can be matched to the correct release.

Ask each consumer owner for one explicit response by the confirmation deadline:

• Ready: migration is complete and test evidence is recorded.
• Ready with condition: the owner can proceed, but names a dependency, temporary safeguard or follow-up date.
• Blocked: the owner cannot proceed and states what is needed.
• Not assessed: no owner has yet reviewed the change.

Record the response, owner and evidence in the tracker. Do not convert silence into Ready.

6. Hand over before the production change

Before production, send the on-call handover with the change record identifier, production window, rollback condition and the current consumer decisions. Include the expected failure signals, such as an increase in validation errors for a changed request field, only where they are documented in the deployment plan.

The release coordinator should make one recorded decision: proceed, proceed with named conditions, delay, or roll back. Attach the final notice and tracker state to that decision.

When the workflow does not work

Stop publication if the specification, tracker and draft disagree. Return the issue to the technical owner, resolve the missing fact in the change record, then update the tracker before drafting again.

If consumer ownership is unknown, publish the technical change notice only to the appropriate internal escalation group and mark the consumer as Not assessed. Do not invent a contact or readiness decision. If dates move, issue a revised notice with the same change record identifier, state which dates changed, and ask consumers to reconfirm their decision.