Get a change request

curl https://api.example.test/v1/change-requests/$CHANGE_REQUEST_ID \  -H "Authorization: Bearer $TOKEN"

One change request with the records it touches. A request of a project the token may not see, or one a client guest neither raised nor asked for, is 404 RESOURCE_NOT_FOUND.

reason is new_requirement, clarification, defect, regulatory, client_request, technical_debt or scope_reduction; status is submitted, under_analysis, awaiting_approval, approved, rejected, implementing, implemented, verified or closed; impact_level is low, medium or high; priority is lowest, low, medium, high or highest.

Requires ability

change-request:view

The token must hold this ability, or the call is refused with 403.

MCP tool

get_change_request

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted in the app under Account Settings, then API Tokens, sent as Authorization: Bearer zg_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team, and optionally to one project, at mint time.

In: header

Path Parameters

changeRequest*string

The request, bound by the middleware.

Formatuuid

Responses

200OKapplication/json

The request with the records it touches.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (a zg_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who registered a row answers FORBIDDEN with the same status, and says so in its own description.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/change-requests/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "b8c9d0e1-f2a3-4b4c-9d5e-6f7a8b9c0d14",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "number": 2,    "reference": "CRM-CR-2",    "title": "Accept vouchers on subscriptions too",    "description": "<p>The client wants the voucher applied to the first renewal as well as the first order.</p>",    "reason": "client_request",    "requested_by": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",    "requester_name": "Bea Analyst",    "stakeholder_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",    "stakeholder_name": "Nadeesha Perera",    "baseline_id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",    "baseline_name": "v1.0 scope",    "affected": [      {        "artefact_type": "requirement",        "artefact_id": "a8b9c0d1-e2f3-4a4b-9c5d-6e7f8a9b0c13",        "reference": "CRM-FR-12",        "title": "Apply a voucher at checkout"      }    ],    "impact_scope": "<p>CRM-FR-12 gains a renewal clause; CRM-142 and its checkout tests change.</p>",    "impact_schedule_days": 5,    "impact_effort_hours": "24.00",    "impact_cost": "1800.00",    "impact_risk": "<p>The renewal job runs unattended; a voucher applied twice would refund twice.</p>",    "impact_level": "medium",    "ai_impact_draft": "<p>Heimdall read the request against the baseline.</p>",    "analysed_at": "2026-11-20T09:15:00+00:00",    "priority": "high",    "status": "awaiting_approval",    "decision_note": null,    "verified_by": null,    "verified_at": null,    "version": 0,    "approved_at": null,    "approved_revision_id": null,    "position": 1,    "created_at": "2026-11-19T14:00:00+00:00",    "updated_at": "2026-11-20T09:15:00+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: ChangeRequestResource;}export interface ChangeRequestResource {  id: string;  project_id: string;  number: number;  reference: string;  title: string;  description: string | null;  reason: string;  requested_by: string | null;  requester_name: string | null;  stakeholder_id: string | null;  stakeholder_name: string | null;  baseline_id: string | null;  baseline_name: string | null;  affected?: Affected[];  impact_scope: string | null;  impact_schedule_days: number | null;  impact_effort_hours?: string | null;  impact_cost?: string | null;  impact_risk: string | null;  impact_level: string | null;  ai_impact_draft?: string | null;  analysed_at: string | null;  priority: string;  status: string;  decision_note: string | null;  verified_by: string | null;  verified_at: string | null;  version: number;  approved_at: string | null;  approved_revision_id: string | null;  position: number;  created_at: string | null;  updated_at: string | null;}export interface Affected {  artefact_type: string;  artefact_id: string;  reference: string | null;  title: string | null;}

Get a change request

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Authorization

Path Parameters

Responses