> ## Documentation Index > Fetch the complete documentation index at: https://docs-attestly.code4source.com/llms.txt > Use this file to discover all available pages before exploring further. # Evaluate a ruleset against a geometry > Runs every check in the ruleset against the submitted geometry and returns a verdict with per-check evidence plus reproducibility metadata. Pass either ``ruleset_id`` (catalog reference) or ``ruleset`` (inline body). Response content is negotiated via the `Accept` header: - `application/json` (default) — `StandardResponse[VerdictResponse]`. - `application/geo+json` — a GeoJSON `FeatureCollection` with one feature per evidence hit; each feature's `properties` carry the check metadata (`check_id`, `severity`, `triggered`, `color`) and evidence metrics (`overlap_area_m2`, `distance_m`, etc.). Pass ``?explain=true`` to return cardinality estimates per set without evaluating user terminals. ## OpenAPI ````yaml /openapi.json post /v1/evaluate openapi: 3.0.3 info: description: >- Geographic compliance API — evaluates polygons against authoritative environmental and regulatory datasets and returns deterministic, audit-ready verdicts. title: Attestly API version: 1.0.0 servers: [] security: [] paths: /v1/evaluate: post: tags: - Ruleset Evaluation summary: Evaluate a ruleset against a geometry description: >- Runs every check in the ruleset against the submitted geometry and returns a verdict with per-check evidence plus reproducibility metadata. Pass either ``ruleset_id`` (catalog reference) or ``ruleset`` (inline body). Response content is negotiated via the `Accept` header: - `application/json` (default) — `StandardResponse[VerdictResponse]`. - `application/geo+json` — a GeoJSON `FeatureCollection` with one feature per evidence hit; each feature's `properties` carry the check metadata (`check_id`, `severity`, `triggered`, `color`) and evidence metrics (`overlap_area_m2`, `distance_m`, etc.). Pass ``?explain=true`` to return cardinality estimates per set without evaluating user terminals. operationId: evaluate_v1_evaluate_post parameters: - description: >- When ``true``, returns cardinality estimates per set without evaluating user terminals. in: query name: explain required: false schema: default: false description: >- When ``true``, returns cardinality estimates per set without evaluating user terminals. title: Explain type: boolean - description: >- When ``true``, includes ruleset-linter findings in ``meta.lint`` alongside the verdict. in: query name: lint required: false schema: default: false description: >- When ``true``, includes ruleset-linter findings in ``meta.lint`` alongside the verdict. title: Lint type: boolean - in: header name: accept required: false schema: nullable: true title: Accept type: string - in: header name: Idempotency-Key required: false schema: nullable: true title: Idempotency-Key type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/EvaluateRequest' required: true responses: '200': content: application/geo+json: schema: title: FeatureCollection type: object application/json: schema: properties: data: $ref: '#/components/schemas/VerdictResponse' errors: description: >- Non-fatal warnings or field-level errors (empty on full success) items: $ref: '#/components/schemas/FieldWarning' title: Errors type: array meta: $ref: '#/components/schemas/Meta' required: - data title: StandardResponse[VerdictResponse] type: object description: Evaluation result. '400': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Malformed request body. '401': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Missing or invalid JWT. '402': description: Subscription is inactive. '403': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Authorization failed. '404': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Ruleset not found. '409': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Resource conflict. '422': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Validation, topology, or compatibility error. '429': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Rate limit exceeded '500': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Unexpected server error. security: - HTTPBearer: [] components: schemas: EvaluateRequest: additionalProperties: false oneOf: - not: required: - ruleset required: - ruleset_id - not: required: - ruleset_id required: - ruleset properties: input: $ref: '#/components/schemas/EvaluationInput' description: >- User-supplied data for the request — geometry, identifier bag, and an optional source CRS. At least one of ``input.geometry`` or ``input.subjects`` MUST be present (enforced inside the ``input`` model). ruleset: additionalProperties: true description: >- Inline ruleset document (same shape as the DSL). Mutually exclusive with ``ruleset_id``. nullable: true title: Ruleset type: object ruleset_as_of: description: >- Point-in-time read for the **ruleset**. Only takes effect when ``ruleset_id`` is passed without ``@version`` — resolves to the highest version whose ``created_at <= ruleset_as_of``. Ignored when ``ruleset_id`` pins a version explicitly or when ``ruleset`` (inline) is used. format: date-time nullable: true title: Ruleset As Of type: string ruleset_id: description: >- Catalog ruleset reference. Accepts ``name@version`` for a pinned version or just ``name`` for the latest. Mutually exclusive with ``ruleset``. maxLength: 256 nullable: true title: Ruleset Id type: string required: - input title: EvaluateRequest type: object VerdictResponse: properties: checks: items: $ref: '#/components/schemas/CheckResultResponse' title: Checks type: array dataset_references: items: $ref: '#/components/schemas/DatasetReferenceResponse' title: Dataset References type: array evaluated_at: format: date-time title: Evaluated At type: string geometry_hash: title: Geometry Hash type: string outcome: $ref: '#/components/schemas/VerdictOutcome' outcome_colors: $ref: '#/components/schemas/OutcomeColorsResponse' description: >- Per-outcome colors from `outcome_colors` in the DSL, merged with palette defaults for any keys the author left unset. program_hash: description: >- SHA-256 of the compiled SQL plus bind params plus per-phase materialization fragments. Same program/inputs → same hash. Use to correlate JSON responses with PDF reports and trace execution back to a specific compiled plan. nullable: true title: Program Hash type: string projections: items: $ref: '#/components/schemas/ProjectionResultResponse' title: Projections type: array ruleset_ref: title: Ruleset Ref type: string signature: nullable: true title: Signature type: string status: $ref: '#/components/schemas/VerdictStatus' required: - ruleset_ref - evaluated_at - geometry_hash - status - outcome - checks - outcome_colors title: VerdictResponse type: object FieldWarning: properties: field: description: Dot-notation path to the field that produced the warning nullable: true title: Field type: string message: description: Human-readable explanation of the warning title: Message type: string type: description: Machine-readable warning type nullable: true title: Type type: string required: - message title: FieldWarning type: object Meta: properties: api_version: default: v1 description: API version string title: Api Version type: string lint: description: >- Advisory lint warnings from the ruleset linter. Populated only when `?lint=true` was passed on the request. Absent otherwise — the envelope is byte-equivalent to the pre-linter baseline. items: $ref: '#/components/schemas/LintWarningResponse' nullable: true title: Lint type: array mode: description: >- Key mode the request was authenticated under: ``test`` (sandbox, no billing) or ``live`` (full billing path). Mirrors the ``X-Attestly-Mode`` response header. Absent for anonymous traffic. nullable: true title: Mode type: string request_id: description: Correlation ID injected by the request-id middleware nullable: true title: Request Id type: string title: Meta type: object ProblemDetail: properties: detail: type: string instance: type: string status: type: integer title: type: string type: format: uri type: string required: - type - title - status type: object EvaluationInput: additionalProperties: false properties: crs: description: >- Optional source CRS of the input geometry (e.g. ``EPSG:31983``). When present, the engine projects the geometry to WGS84 before evaluation. When absent, geometry is assumed to be WGS84. Accepts EPSG codes, PROJ strings, or WKT — anything ``pyproj`` can parse. Unknown CRSes return HTTP 400. maxLength: 256 nullable: true title: Crs type: string geometry: description: >- Optional GeoJSON Polygon, MultiPolygon, or Point. Required when the program has a spatial set joining ``$input``; may be omitted for subject-only evaluations. discriminator: mapping: MultiPolygon: $ref: '#/components/schemas/MultiPolygon' Point: $ref: '#/components/schemas/Point' Polygon: $ref: '#/components/schemas/Polygon' propertyName: type nullable: true oneOf: - $ref: '#/components/schemas/Polygon' - $ref: '#/components/schemas/MultiPolygon' - $ref: '#/components/schemas/Point' title: Geometry scheme: $ref: '#/components/schemas/SchemeInput' description: >- Optional typed identifier (``{ type, value }``). Required when the program has a subject set joining ``$input``. nullable: true title: EvaluationInput type: object CheckResultResponse: properties: color: description: >- Author-supplied `checks[].color` from the ruleset DSL, or a deterministic hash-derived default so clients always have one. title: Color type: string error: nullable: true title: Error type: string evidence: items: $ref: '#/components/schemas/FeatureEvidenceResponse' title: Evidence type: array id: title: Id type: string raster_band: description: >- Populated only for checks whose threshold reads a ``raster_stat`` projection. The 1-based band index that was sampled. nullable: true title: Raster Band type: integer raster_nodata_count: description: >- Number of nodata pixels that fell inside the input geometry but were excluded from the reduction. ``null`` for non-raster checks. nullable: true title: Raster Nodata Count type: integer raster_pixel_count: description: >- Number of valid pixels (geometry ∩ raster minus nodata) the raster reduction was computed over. ``null`` for non-raster checks. nullable: true title: Raster Pixel Count type: integer severity: $ref: '#/components/schemas/Severity' status: $ref: '#/components/schemas/CheckStatus' total_matched: description: >- Total number of rows in the set the check evaluated over. ``evidence`` is capped at ``PROGRAM_MAX_EVIDENCE_PER_CHECK`` — when ``total_matched > len(evidence)`` the UI should indicate truncation. ``null`` for failed checks or terminals that emit no evidence (e.g. ``merge``). nullable: true title: Total Matched type: integer triggered: title: Triggered type: boolean required: - id - severity - triggered - status - color title: CheckResultResponse type: object DatasetReferenceResponse: properties: collected_at_latest: format: date-time nullable: true title: Collected At Latest type: string source_dataset: title: Source Dataset type: string source_name: title: Source Name type: string source_url: title: Source Url type: string status: $ref: '#/components/schemas/CheckStatus' default: ok required: - source_name - source_dataset - source_url title: DatasetReferenceResponse type: object VerdictOutcome: enum: - compliant - warning - non_compliant - degraded title: VerdictOutcome type: string OutcomeColorsResponse: properties: compliant: title: Compliant type: string degraded: title: Degraded type: string non_compliant: title: Non Compliant type: string warning: title: Warning type: string required: - compliant - warning - non_compliant - degraded title: OutcomeColorsResponse type: object ProjectionResultResponse: properties: color: description: >- Author-supplied `projections[].color` from the ruleset DSL, or a deterministic hash-derived default. title: Color type: string error: nullable: true title: Error type: string evidence: description: >- Up to ``PROGRAM_MAX_EVIDENCE_PER_CHECK`` matching features. Empty for `merge` projections (the merged geometry replaces per-feature evidence) and for FAILED results. items: $ref: '#/components/schemas/FeatureEvidenceResponse' title: Evidence type: array id: title: Id type: string kind: $ref: '#/components/schemas/TerminalKind' merged_area_m2: description: >- Populated only for `merge` projections. Geodesic area in square meters of the unified geometry. nullable: true title: Merged Area M2 type: number merged_geometry_wkt: description: >- Populated only for `merge` projections. WKT of the unified geometry across the referenced set (optionally simplified). nullable: true title: Merged Geometry Wkt type: string raster_band: description: >- Populated only for ``raster_stat`` projections. The 1-based band index that was sampled. nullable: true title: Raster Band type: integer raster_nodata_count: description: >- Number of nodata pixels that fell inside the input geometry but were excluded from the reduction. ``null`` for non-raster projections. nullable: true title: Raster Nodata Count type: integer raster_pixel_count: description: >- Number of valid pixels (geometry ∩ raster minus nodata) the raster reduction was computed over. ``null`` for non-raster projections. nullable: true title: Raster Pixel Count type: integer status: $ref: '#/components/schemas/CheckStatus' total_matched: description: >- See ``CheckResultResponse.total_matched``. ``null`` for ``merge`` projections (no per-feature evidence) or FAILED. nullable: true title: Total Matched type: integer value: description: >- Populated only for `aggregate` projections. Numeric result of the aggregator over the referenced set. nullable: true title: Value type: number required: - id - kind - status - color title: ProjectionResultResponse type: object VerdictStatus: enum: - ok - degraded title: VerdictStatus type: string LintWarningResponse: properties: code: description: Stable rule identifier, e.g. 'LNT001'. pattern: ^LNT[0-9]{3}$ title: Code type: string message: description: Human-readable description naming the offending element. title: Message type: string path: description: >- Dot/brace path to the offending node (e.g. `sets.foo`). Null for cross-cutting findings with no single location. nullable: true title: Path type: string severity: $ref: '#/components/schemas/LintSeverity' description: >- `warning` for smells that are almost always worth fixing; `info` for suggestions that may be intentional. required: - code - message - severity title: LintWarningResponse type: object MultiPolygon: description: MultiPolygon Model properties: bbox: anyOf: - items: type: number maxItems: 4 minItems: 4 type: array - items: type: number maxItems: 6 minItems: 6 type: array nullable: true title: Bbox coordinates: items: items: items: anyOf: - $ref: '#/components/schemas/Position2D' - $ref: '#/components/schemas/Position3D' minItems: 4 type: array type: array title: Coordinates type: array type: enum: - MultiPolygon title: Type type: string required: - type - coordinates title: MultiPolygon type: object Point: description: Point Model properties: bbox: anyOf: - items: type: number maxItems: 4 minItems: 4 type: array - items: type: number maxItems: 6 minItems: 6 type: array nullable: true title: Bbox coordinates: anyOf: - $ref: '#/components/schemas/Position2D' - $ref: '#/components/schemas/Position3D' title: Coordinates type: enum: - Point title: Type type: string required: - type - coordinates title: Point type: object Polygon: description: Polygon Model properties: bbox: anyOf: - items: type: number maxItems: 4 minItems: 4 type: array - items: type: number maxItems: 6 minItems: 6 type: array nullable: true title: Bbox coordinates: items: items: anyOf: - $ref: '#/components/schemas/Position2D' - $ref: '#/components/schemas/Position3D' minItems: 4 type: array title: Coordinates type: array type: enum: - Polygon title: Type type: string required: - type - coordinates title: Polygon type: object SchemeInput: additionalProperties: false properties: type: description: >- Typed identifier scheme (``:``, lowercase, max 65 chars). Examples: ``br:cnpj``, ``br:cpf``, ``ofac:sdn``. example: br:cnpj pattern: ^[a-z][a-z0-9-]{0,15}:[a-z][a-z0-9._-]{0,47}$ title: Type type: string value: description: >- Identifier value. Cosmetic separators (spaces, dashes, dots, slashes, parens, etc.) and case differences are stripped at validation time — ``"12.345.678/0001-90"`` and ``"12345678000190"`` are equivalent. The same canonicalization is applied at ingest, so ``equals`` matches are deterministic. example: 12.345.678/0001-90 maxLength: 256 minLength: 1 title: Value type: string required: - type - value title: SchemeInput type: object FeatureEvidenceResponse: properties: distance_m: nullable: true title: Distance M type: number name: nullable: true title: Name type: string overlap_area_m2: nullable: true title: Overlap Area M2 type: number overlap_pct_feature: nullable: true title: Overlap Pct Feature type: number overlap_pct_input: nullable: true title: Overlap Pct Input type: number properties: additionalProperties: true title: Properties type: object source_id: title: Source Id type: string source_name: title: Source Name type: string required: - source_name - source_id title: FeatureEvidenceResponse type: object Severity: enum: - critical - high - medium - low - info title: Severity type: string CheckStatus: enum: - ok - failed title: CheckStatus type: string TerminalKind: enum: - exists - threshold - count - overlap_ratio - min_distance_m - max_distance_m - total_area_m2 - total_perimeter_m - aggregate - merge - raster_stat title: TerminalKind type: string LintSeverity: enum: - warning - info title: LintSeverity type: string Position2D: items: title: Longitude type: number maxItems: 2 minItems: 2 type: array Position3D: items: title: Longitude type: number maxItems: 3 minItems: 3 type: array securitySchemes: HTTPBearer: scheme: bearer type: http ````