SustemaDeveloper sign in

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