Response envelope - Cotality developer portal

One shape for every response

Every Cotality MCP tool and REST endpoint returns the same top-level envelope. Parse these four fields on every call, before reading tool-specific payload.

{
  "success": true,
  "count": 1,
  "data": [ /* tool-specific result objects */ ],
  "messages": []
}

Fields

Field	Type	Always present	Meaning
`success`	`boolean`	Yes	Whether the call completed successfully. Gate all `data` reads on this.
`count`	`integer`	Yes	Number of items in `data`.
`data`	`array`	Yes	Tool-specific payload. Shape differs per tool.
`messages`	`array`	Yes	Warnings, deprecations, partial-match notices, and info. Always surface non-empty values.

Rules for consumers

Gate on success

If success is false, do not read data. Route to error handling.

Respect count

Iterate exactly count items from data. Do not assume a single result — parcels, properties, and geographies can return multiple records.

Read messages on every call

messages carries freshness notes, partial-match warnings, and deprecation notices. An empty array is normal. A non-empty array always contains something the user or agent should know about.

Error envelope

When success is false, the error detail is in messages:

{
  "success": false,
  "count": 0,
  "data": [],
  "messages": [
    { "code": "ENTITLEMENT_DENIED", "message": "Asset not licensed for this token." }
  ]
}

See Error handling for the full list of codes and agent actions.

Example — property characteristics (abridged)

{
  "success": true,
  "count": 1,
  "data": [{
    "clip": "123456789",
    "propertyCharacteristics": {
      "land": { "landUseCodeDescription": "Single Family Residence" },
      "structure": [{ "actualYearBuilt": 2012, "livingSquareFootage": 2450 }]
    }
  }],
  "messages": []
}

For AI agents: after every tool call, check messages before summarising results. Non-empty messages often explain why a result is partial, estimated, or about to change.

​One shape for every response

​Fields

​Rules for consumers

​Error envelope

​Example — property characteristics (abridged)

One shape for every response

Fields

Rules for consumers

Error envelope

Example — property characteristics (abridged)