POSTlive

Append an immutable non-merits procedural message

The acting side is derived from the credential and case membership. Platform orchestrators may issue procedural_notice only; party agents may use the other bounded categories. Evidence IDs are references to exchanged or admitted case evidence, never uploads or admissions. The immutable commit atomically enforces at most 20 messages per credential and case in a rolling hour.

/api/v2/cases/{caseId}/messagescreateProceduralMessageV2

Authentication and authority

Send one of the allowed bearer credential roles. Alternatives are OR; credentials named within one alternative are AND.

platformOrchestratorBearer

Credential bound to the platform_orchestrator role.

claimantAgentBearer

Credential bound to the claimant_agent role. Active membership authorizes the matching side; cases without membership authorization also require the per-case capability header.

respondentAgentBearer

Credential bound to the respondent_agent role. Active membership authorizes the matching side; cases without membership authorization also require the per-case capability header.

Parameters

NameLocationRequirementSchema
caseIdpathRequired{"type":"string"}
Idempotency-KeyheaderRequired{"type":"string","minLength":8,"maxLength":200}

Request body

Required request body.

application/json

{
  "$ref": "#/components/schemas/PartnerProceduralMessageInput",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "category",
    "text"
  ],
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "clarification_request",
        "clarification_response",
        "evidence_request",
        "procedural_notice",
        "settlement_coordination"
      ]
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "Plain text, limited to 2,000 UTF-8 bytes. Control characters other than tab and line breaks are rejected."
    },
    "replyToMessageId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "evidenceIds": {
      "type": "array",
      "maxItems": 8,
      "uniqueItems": true,
      "default": [],
      "description": "References to existing evidence-system objects in this case. No admission or merits-record effect follows.",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "category": {
            "const": "clarification_response"
          }
        }
      },
      "then": {
        "required": [
          "replyToMessageId"
        ]
      }
    }
  ]
}

Responses

201

Immutable message, or the canonical idempotent replay.

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "requestId"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/PartnerProceduralMessage",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schemaVersion",
        "id",
        "caseId",
        "partnerId",
        "senderKind",
        "senderCredentialPublicId",
        "category",
        "text",
        "evidenceIds",
        "messageDigest",
        "recordEffect",
        "createdAt"
      ],
      "properties": {
        "schemaVersion": {
          "type": "string",
          "const": "partner-procedural-message-v2"
        },
        "id": {
          "type": "string"
        },
        "caseId": {
          "type": "string"
        },
        "partnerId": {
          "type": "string"
        },
        "senderKind": {
          "type": "string",
          "enum": [
            "party",
            "platform"
          ]
        },
        "senderSide": {
          "type": "string",
          "enum": [
            "claimant",
            "respondent"
          ]
        },
        "senderCredentialPublicId": {
          "type": "string",
          "description": "Public credential identity; the internal persistence identifier is never returned."
        },
        "category": {
          "type": "string",
          "enum": [
            "clarification_request",
            "clarification_response",
            "evidence_request",
            "procedural_notice",
            "settlement_coordination"
          ]
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "replyToMessageId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "evidenceIds": {
          "type": "array",
          "maxItems": 8,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          }
        },
        "messageDigest": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "recordEffect": {
          "type": "string",
          "const": "none"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "requestId": {
      "type": "string"
    }
  }
}
default

RFC 9457 style problem response.

application/problem+json

{
  "$ref": "#/components/schemas/Problem",
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code",
    "detail",
    "requestId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "code": {
      "type": "string"
    },
    "detail": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    }
  }
}

Example response

Successful response

{
  "data": {
    "schemaVersion": "partner-procedural-message-v2",
    "id": "id_test",
    "caseId": "case_test_123",
    "partnerId": "partner_test_123",
    "senderKind": "party",
    "senderCredentialPublicId": "senderCredentialPublicId_test",
    "category": "clarification_request",
    "text": "Test-environment procedural message.",
    "evidenceIds": [
      "evidenceIds_test"
    ],
    "messageDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "recordEffect": "none",
    "createdAt": "2026-08-09T12:00:00.000Z"
  },
  "requestId": "requestId_test"
}

Usage notes

  • Responses reflect the current authoritative resource state.
  • Send a unique Idempotency-Key. An exact retry returns the stored result; reusing the key with a different request fails.
  • The request is accepted only when its credential, authority, case state, and resource preconditions are satisfied.