Sustema

ENTITY developer reference

Read an owned field report

Candidate documentation for reading and synthetic examples. Account creation, live API access, SDKs, collections and MCP are not available here. A released service profile and matching integration instructions are required before use.

This is a documentation reading view of an unreleased candidate, not a downloadable replacement schema. Public wire names, types and constraints are retained except for the explicitly marked private-only subsets and route patterns. Private governance references are explained in public language. Use only a separately released, verified generation for clients. Read the explicit exclusions.

GET /v1/feedback/{feedback_id}

Operation identifier: getFeedback

Read an owned field report. The field-feedback rules govern private allegations, original-scope checks, no customer debit and bounded Sustema-funded rechecks. Public HTTP/MCP requires the original reporting integration service principal with current feedback.read and original scope. It cannot borrow a human steward/named relation or an unspecified machine-sharing grant. Every current credential/action/profile/source/retention guard still applies. Original-report ownership, stewardship and explicit report access in the signed-in console require their own current human permissions; this public operation grants none of them. Original reporting integration service principal with current feedback.read and original report scope. No human steward, named feedback relation or unspecified machine-sharing issuer is available on public HTTP/MCP. All current credential/action/profile/source/retention and opaque foreign-resource guards apply.

Entity-Service-Profile carries the accepted profile_id; the endpoint pins its separate immutable revision. The retained template parameter description says “revision”; follow this current interpretation when reading that historical wording. No reserved example URL in the definitions is a live service destination.

Authentication

Apply the operation’s security requirement when present, otherwise the contract default below. These definitions do not provision access or qualify an authentication flow.

[
  {
    "bearerAuth": []
  }
]
Security scheme definitions
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "description": "Validated OAuth access token, never an ID token. Issuer/audience/token endpoint and scope mapping are deployment-profile values. ENTITY current role, data and budget policy additionally applies."
  }
}

Request parameters

Headers, path and query parameters from the candidate contract. Operation-specific definitions take precedence over inherited definitions with the same name and location. Request body fields appear in the reading view below.

Entity-Service-Profile

header · Required

Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation.

Reading definition for Entity-Service-Profile
{
  "name": "Entity-Service-Profile",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "maxLength": 4096,
    "x-profile-maxLength": "string_characters_max"
  },
  "description": "Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation."
}

feedback_id

path · Required

Reading definition for feedback_id
{
  "name": "feedback_id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "maxLength": 36
  }
}

Request and response contract

The candidate operation is shown below with the declared documentation-only public-meaning projection. References open the corresponding public schema. No server URL or credential is supplied by this page.

{
  "operationId": "getFeedback",
  "summary": "Read an owned field report",
  "description": "Read an owned field report. The field-feedback rules govern private allegations, original-scope checks, no customer debit and bounded Sustema-funded rechecks. Public HTTP/MCP requires the original reporting integration service principal with current feedback.read and original scope. It cannot borrow a human steward/named relation or an unspecified machine-sharing grant. Every current credential/action/profile/source/retention guard still applies. Original-report ownership, stewardship and explicit report access in the signed-in console require their own current human permissions; this public operation grants none of them. Original reporting integration service principal with current feedback.read and original report scope. No human steward, named feedback relation or unspecified machine-sharing issuer is available on public HTTP/MCP. All current credential/action/profile/source/retention and opaque foreign-resource guards apply.",
  "tags": [
    "Data quality feedback"
  ],
  "parameters": [
    {
      "$ref": "#/components/parameters/ServiceProfile"
    },
    {
      "name": "feedback_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid",
        "maxLength": 36
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Proposed governed response; no deployed endpoint.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "ETag": {
          "schema": {
            "type": "string",
            "pattern": "^\"[1-9][0-9]*\"$"
          },
          "description": "Quoted decimal owned FeedbackResult.revision, identical to the response data revision."
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/FeedbackResponse"
          },
          "example": {
            "data": {
              "feedback_id": "00000000-0000-4000-8000-000000000007",
              "revision": 1,
              "state": "received",
              "projection": "full_permitted",
              "target": {
                "kind": "claim",
                "receipt_id": "00000000-0000-4000-8000-000000000003",
                "subject": {
                  "entity_id": "00000000-0000-4000-8000-000000000001",
                  "environment": "synthetic-review",
                  "manifest_id": "00000000-0000-4000-8000-000000000002",
                  "subject_type": "legal_entity"
                },
                "field_path": "/data/claims/0",
                "claim_id": "00000000-0000-4000-8000-000000000004",
                "claim_version_id": "00000000-0000-4000-8000-000000000005"
              },
              "reason_code": "accepted",
              "explanation": "Report recorded. Eligibility and bounded maintenance capacity will be checked. No customer credits were used.",
              "next_action": "poll_status",
              "created_at": "2026-09-14T05:00:00Z",
              "updated_at": "2026-09-14T05:00:00Z",
              "expires_at": "2026-09-21T05:00:00Z",
              "recheck_reference": null,
              "updated_subject": null,
              "related_adjustment_request_id": null,
              "customer_debit_units": "0",
              "policy_revision": "synthetic-proposed-only-1"
            },
            "meta": {
              "request_id": "00000000-0000-4000-8000-000000000006",
              "served_at": "2026-09-14T05:00:00Z",
              "profile_revision": "synthetic-feedback-1",
              "synthetic": true,
              "replayed": false,
              "warnings": [
                "Illustrative only; no company or service is real."
              ]
            }
          }
        }
      }
    },
    "422": {
      "description": "Bounded delivery refusal; no new work or customer debit. Return only current-authorised finite delivery guidance.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FeedbackProblem"
              },
              {
                "properties": {
                  "code": {
                    "const": "limit_out_of_range"
                  },
                  "status": {
                    "const": 422
                  },
                  "retry_action": {
                    "const": "do_not_retry"
                  }
                }
              }
            ]
          }
        }
      }
    },
    "default": {
      "description": "FeedbackProblem; status/retry bound by errors.json, same-key retry after uncertain submission; no charge or arbitrary provider work.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/FeedbackProblem"
          }
        }
      }
    }
  },
  "x-permission": "feedback.read",
  "x-billable": false,
  "x-commercial-effect": "zero_customer_units",
  "x-recovery-lane": "feedback",
  "x-entitlement-rule": "Current feedback grant plus ownership of original receipt/report; no spendable balance needed. Current data rights independently gate payload/updated-result disclosure.",
  "x-owned-feedback-projection": "FeedbackResult.revision is authoritative for public CAS. REST ETag is quoted decimal revision; MCP constructs If-Match from that same revision. Every error and header follows owned public guards.",
  "x-cross-adapter-bound": {
    "operation": "getFeedback",
    "rule": "#/x-delivery-bound-contract",
    "before_settlement": true
  },
  "x-original-resource-relation": "Original reporting integration service principal with current feedback.read and original report scope. No human steward, named feedback relation or unspecified machine-sharing issuer is available on public HTTP/MCP. All current credential/action/profile/source/retention and opaque foreign-resource guards apply."
}

Referenced schemas

Includes schemas used by this operation and its shared or inherited parameters. Open a schema to follow its related definitions.

Shared parameter definitions
{
  "Cursor": {
    "name": "cursor",
    "in": "query",
    "required": false,
    "schema": {
      "type": "string",
      "maxLength": 4096,
      "x-profile-maxLength": "string_characters_max"
    },
    "description": "Opaque signed cursor bound to query, organisation, environment, profile, rights and index/publication generation."
  },
  "IdempotencyKey": {
    "name": "Idempotency-Key",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Random UUID for one logical operation, including billed GETs. Same request/key/time replays without a second charge; ENTITY application semantics."
  },
  "Manifest": {
    "name": "manifest_id",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Manifest returned by identity/search. A compatibility-bound follow-on read, not unrestricted historical query. Current rights and retention apply."
  },
  "MaxUnits": {
    "name": "Entity-Max-Units",
    "in": "header",
    "required": false,
    "schema": {
      "$ref": "#/components/schemas/Units"
    },
    "description": "Caller ceiling in the accepted offer atomic unit; cannot increase organisation authority."
  },
  "OperationCreated": {
    "name": "Entity-Operation-Created-At",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "date-time",
      "maxLength": 35
    },
    "description": "Original creation instant, unchanged on retry. New keys outside the profile admission/skew window are refused even after tombstone expiry."
  },
  "PageSize": {
    "name": "page_size",
    "in": "query",
    "required": false,
    "schema": {
      "type": "integer",
      "minimum": 1,
      "x-profile-maximum": "page_size_max"
    },
    "description": "Default and maximum from the active profile."
  },
  "ReceiptContext": {
    "name": "Entity-Receipt-Context",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Readable own-organisation receipt containing the requested entity/manifest. Binds follow-on evidence/module reads to a known permitted result within its retention window; this is not unrestricted historical access."
  },
  "ServiceProfile": {
    "name": "Entity-Service-Profile",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "maxLength": 4096,
      "x-profile-maxLength": "string_characters_max"
    },
    "description": "Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation."
  }
}
Inherited path parameters
[]

All API operations