Use this when: a contract artifact (OpenAPI, GraphQL, protobuf, AsyncAPI, MCP manifests, or agent tool schemas) changes before merge, deploy, publish, or tool registration; AND any agent-executed operation with no supported contract type — send type agent_operation. Do not call for documentation-only changes, static readiness scoring, or receipt verification. Use analyze for risk only; authorize requires context.operation. Skipping this call is not permission. Absence of a key is not permission. Inputs: preflight_mode is required: "analyze" (risk only; no receipt, no execution_action) or "authorize" (may mint a receipt; requires context.operation — merge is not deploy is not publish). Supply exactly one artifact source: artifacts[] (1–20 items, each {id, type, before, after} as the FULL spec/schema text, not a path or URL; type is openapi|graphql|grpc|asyncapi|mcp_manifest|agent_tools|agent_operation) XOR derivation="server" (server reads GitHub Compare; needs context.repository + context.base + context.head; sending artifacts[] together is 400). Grant fields sit in one object, execution_grant_request {include_execution_grant, grant_version, tenant_id, executor_id, adapter_id, target_uri, expected_state_token, state_nonce, audience, policy_hash}; analyze ignores it; required is preflight_mode only. previous_receipt is a chain token base64url(body).base64url(signature) to LINK a prior decision — it does not re-verify; use coderifts.verify_receipt instead; for details of a past decision use coderifts.get_decision_details instead. idempotency_key replays authorize only (24h), never analyze.
View input schema
{
"type": "object",
"properties": {
"artifacts": {
"type": "array",
"description": "1–20 contract documents analyzed together. Each item is {id, type, before, after} where before/after are the FULL document strings (YAML/JSON/proto text), not URLs or file paths. Omit this array entirely when derivation=\"server\".",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Caller-chosen id, unique within the bundle"
},
"type": {
"type": "string",
"enum": [
"openapi",
"graphql",
"grpc",
"asyncapi",
"mcp_manifest",
"agent_tools",
"agent_operation"
],
"description": "Artifact kind. One of openapi, graphql, grpc, asyncapi, mcp_manifest, agent_tools, agent_operation. Contract types determine how before/after text is parsed. agent_operation: An opaque proposed agent operation for which no supported contract-artifact type applies. CodeRifts does not semantically analyze this content and does not issue an execution grant. Not inferred from the filename."
},
"before": {
"type": "string",
"description": "The baseline document as raw text (the spec/schema/manifest body). Empty string means \"no prior version\" (create), not \"load from disk\"."
},
"after": {
"type": "string",
"description": "The proposed document as raw text, same kind as before. Must be the bytes you intend to merge/deploy/publish, not a diff."
}
},
"required": [
"id",
"type",
"before",
"after"
]
}
},
"context": {
"type": "object",
"description": "Optional apply-site context folded into the bundle fingerprint. operation distinguishes merge vs deploy vs publish (and other labels); the server accepts any non-empty string; conventional values: merge, deploy, tool_call, publish. The receipt/gate must match this label.",
"properties": {
"operation": {
"type": "string",
"description": "Application operation for this change set (fingerprint + envelope). Server accepts any non-empty string; conventional values: merge, deploy, tool_call, publish. Merge is not deploy is not publish — the receipt/gate must match this label."
},
"environment": {
"type": "string",
"description": "Target environment (e.g. production, staging, npm) — optional; folded into fingerprint when set."
},
"repository": {
"type": "string",
"description": "Repository identity (optional; fingerprint context)"
},
"branch": {
"type": "string",
"description": "Branch name (optional; fingerprint context)"
},
"pull_request": {
"description": "Pull request id when applicable (optional; fingerprint context)",
"oneOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"policy_profile": {
"type": "string",
"description": "Policy profile name (optional; fingerprint context)"
},
"base": {
"type": "string",
"description": "Base commit/ref SHA the change set was computed against (optional; PR/commit identity)"
},
"head": {
"type": "string",
"description": "Head commit/ref SHA of the proposed change (optional; PR/commit identity)"
},
"target_id": {
"type": "string",
"description": "Optional apply-site target (IntentContext parity; not folded into the bundle fingerprint)"
},
"target_uri": {
"type": "string",
"description": "Optional apply-site URI the cr.exec.v2 grant binds (handler fallback: input.target_uri, then context.target_uri, then repository/head-derived). Distinct from target_id."
},
"fingerprint": {
"type": "string",
"description": "Optional change fingerprint (IntentContext parity; not folded into the bundle fingerprint)"
},
"audience": {
"type": "string",
"description": "Optional audience (IntentContext parity; REST/MCP accept, server-derived audience still wins on the envelope)"
}
}
},
"previous_receipt": {
"type": "string",
"description": "Optional prior chain token to LINK this call into a receipt chain: base64url(body).base64url(signature). Linking is not verification — a linked token is not re-checked here; use verify_receipt."
},
"execution_grant_request": {
"type": "object",
"description": "Authorize + include_execution_grant only: the execution-grant request fields. Analyze ignores them. Flat root-level spellings are also accepted; the same field sent both ways with different values is INVALID_INPUT.",
"properties": {
"include_execution_grant": {
"type": "boolean",
"description": "Authorize only. When true on an allow-class authorize, the response includes a signed execution_grant, or HTTP 503 SIGNER_UNAVAILABLE — never an unsigned grant. Default false. Analyze ignores this flag. Ignored unless preflight_mode=\"authorize\"."
},
"state_nonce": {
"type": "string",
"description": "Authorize+grant only. Opaque nonce copied into the signed grant as its own field (not folded into scope_hash). Absent → BEARER grant. Ignored unless include_execution_grant is true."
},
"grant_version": {
"type": "string",
"enum": [
"v1",
"v2"
],
"x-coderifts-effective-default": "v2",
"x-coderifts-default-changes-at": "2026-09-18",
"description": "Grant envelope to mint when include_execution_grant is true. Omitting this yields cr.exec.v1 until 2026-09-18 and cr.exec.v2 on and after it (see x-coderifts-effective-default / x-coderifts-default-changes-at). The response meta.grant_version is the version actually issued. An explicit value always wins — pin \"v1\" to keep current behaviour with no code change on the date."
},
"tenant_id": {
"type": "string",
"description": "Authorize+grant v2 only. Tenant the grant is issued under. ASCII slug. When omitted the server uses \"default\" — pin it if you are not on the default tenant."
},
"executor_id": {
"type": "string",
"description": "Authorize+grant v2 only. Executor identity the grant is bound to (example: agent:ci-bot, host:github-actions). Empty/absent is not \"any executor\"."
},
"adapter_id": {
"type": "string",
"description": "Authorize+grant v2 only. Adapter that will apply the change. Conventional values: fs, postgres, git. Must match the adapter the executor actually uses; a git grant does not authorize an fs write."
},
"target_uri": {
"type": "string",
"description": "Authorize+grant v2 only. URI the grant binds (example: git://owner/repo.git/refs/heads/main). Fallback if omitted: context.target_uri, then repository/head-derived. Distinct from context.target_id."
},
"expected_state_token": {
"type": "string",
"description": "Authorize+grant v2 only. Compare-and-swap token the executor must observe at apply time (the \"before\" state). Signed as its own field. Omit only if the adapter has no prior state; do not send a placeholder."
},
"audience": {
"type": "string",
"description": "Requester identity for the decision envelope. Accepted here; the server-derived audience wins when both are present."
},
"policy_hash": {
"type": "string",
"description": "Authorize+grant v2 only. Policy identity bound into the grant, sha256: + 64 hex. When supplied, apply must use that same policy; a different policy is a different grant."
}
}
},
"response_detail": {
"type": "string",
"enum": [
"control",
"standard",
"full"
],
"description": "How much of the response to return. control = the fields an agent branches on; standard = control + the human report and labelled break rows (the MCP default); full = everything (the REST default). Every value is copied from the full response."
},
"idempotency_key": {
"type": "string",
"description": "Optional client key; in authorize mode, a repeat with the same key + body replays the original decision (24h). Analyze responses are not replayed."
},
"preflight_mode": {
"type": "string",
"enum": [
"analyze",
"authorize"
],
"description": "REQUIRED. \"analyze\" = informational risk only (no decision/execution_action/safe_for_agent; analysis_outcome + may_execute:false). \"authorize\" = operation-bound path; may mint a receipt (requires context.operation). Decision Spec 2.0: omission is INVALID_INPUT. Do not pin 1.0 — that pin retired."
},
"decision_spec_version": {
"type": "string",
"enum": [
"2.0"
],
"description": "Optional. Omit or '2.0' = current contract. '1.0' retired (INVALID_INPUT); do not pin 1.0."
},
"derivation": {
"type": "string",
"enum": [
"server"
],
"description": "\"server\" = the server derives artifacts[] from GitHub Compare via the App installation. Allowed only when context.repository, context.base and context.head are all present and the tenant has a proven binding for that repository. Do not send artifacts[] in the same call (400 — one source of truth). Omit this field for the caller-supplied artifacts[] path."
}
},
"required": [
"preflight_mode"
],
"if": {
"properties": {
"preflight_mode": {
"const": "authorize"
}
},
"required": [
"preflight_mode"
]
},
"then": {
"required": [
"context"
],
"properties": {
"context": {
"type": "object",
"required": [
"operation"
],
"properties": {
"operation": {
"type": "string",
"minLength": 1
}
}
}
}
}
}