> ## 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.

# Return reference areas intersecting a geometry

> Accepts a GeoJSON Polygon, MultiPolygon, or Point and returns the reference areas that intersect it. No compliance verdict is applied — callers wire their own downstream logic.

Response content is negotiated via the `Accept` header:
- `application/json` (default) — `StandardResponse[IntersectionsResponse]`.
- `application/geo+json` — a GeoJSON `FeatureCollection`.
- `application/x-ndjson` — server-side fan-out streamed as NDJSON, one frame per source completion (`meta`, then `source` per candidate, then `summary`). Lets callers render incrementally without per-source HTTP requests.



## OpenAPI

````yaml /openapi.json post /v1/intersections
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/intersections:
    post:
      tags:
        - Intersections
      summary: Return reference areas intersecting a geometry
      description: >-
        Accepts a GeoJSON Polygon, MultiPolygon, or Point and returns the
        reference areas that intersect it. No compliance verdict is applied —
        callers wire their own downstream logic.


        Response content is negotiated via the `Accept` header:

        - `application/json` (default) —
        `StandardResponse[IntersectionsResponse]`.

        - `application/geo+json` — a GeoJSON `FeatureCollection`.

        - `application/x-ndjson` — server-side fan-out streamed as NDJSON, one
        frame per source completion (`meta`, then `source` per candidate, then
        `summary`). Lets callers render incrementally without per-source HTTP
        requests.
      operationId: find_intersections_v1_intersections_post
      parameters:
        - 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/IntersectionsRequest'
        required: true
      responses:
        '200':
          content:
            application/geo+json:
              schema:
                title: FeatureCollection
                type: object
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/IntersectionsResponse'
                  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[IntersectionsResponse]
                type: object
            application/x-ndjson:
              schema:
                title: NDJSON stream
                type: string
          description: Intersections returned.
        '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 token
        '402':
          description: User subscription is inactive or past due
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Authorization failed.
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Resource 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: Request body failed schema validation
        '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:
    IntersectionsRequest:
      properties:
        input:
          $ref: '#/components/schemas/SpatialInput'
          description: >-
            User-supplied data for the request — geometry plus an optional
            source CRS. Required.
        reference_areas_country_iso3:
          description: ISO3 filter (e.g. 'BRA').
          maxLength: 3
          minLength: 3
          nullable: true
          title: Reference Areas Country Iso3
          type: string
        reference_areas_source:
          description: Source filter (e.g. 'wfs').
          maxLength: 64
          nullable: true
          title: Reference Areas Source
          type: string
        reference_id:
          description: Optional caller-provided reference identifier for audit/trace.
          maxLength: 128
          nullable: true
          title: Reference Id
          type: string
      required:
        - input
      title: IntersectionsRequest
      type: object
    IntersectionsResponse:
      properties:
        intersections:
          items:
            $ref: '#/components/schemas/ReferenceAreaHit'
          title: Intersections
          type: array
        reference_areas_check:
          $ref: '#/components/schemas/ReferenceAreasCheckStatus'
          default: ok
        reference_id:
          nullable: true
          title: Reference Id
          type: string
      title: IntersectionsResponse
      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
    SpatialInput:
      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: >-
            GeoJSON Polygon, MultiPolygon, or Point used as the input shape for
            the request.
          discriminator:
            mapping:
              MultiPolygon:
                $ref: '#/components/schemas/MultiPolygon'
              Point:
                $ref: '#/components/schemas/Point'
              Polygon:
                $ref: '#/components/schemas/Polygon'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/Polygon'
            - $ref: '#/components/schemas/MultiPolygon'
            - $ref: '#/components/schemas/Point'
          title: Geometry
      required:
        - geometry
      title: SpatialInput
      type: object
    ReferenceAreaHit:
      properties:
        country_iso3:
          nullable: true
          title: Country Iso3
          type: string
        feature_url:
          nullable: true
          title: Feature Url
          type: string
        indexed_at:
          format: date-time
          nullable: true
          title: Indexed At
          type: string
        name:
          title: Name
          type: string
        overlap_area_m2:
          minimum: 0
          title: Overlap Area M2
          type: number
        overlap_pct_feature:
          maximum: 1
          minimum: 0
          title: Overlap Pct Feature
          type: number
        overlap_pct_input:
          description: 0.0 when the input has no 2D area (Point input).
          maximum: 1
          minimum: 0
          title: Overlap Pct Input
          type: number
        properties:
          additionalProperties: true
          title: Properties
          type: object
        source_dataset:
          nullable: true
          title: Source Dataset
          type: string
        source_id:
          title: Source Id
          type: string
        source_name:
          title: Source Name
          type: string
        source_url:
          nullable: true
          title: Source Url
          type: string
        source_version:
          nullable: true
          title: Source Version
          type: string
      required:
        - source_name
        - source_id
        - name
        - overlap_area_m2
        - overlap_pct_input
        - overlap_pct_feature
      title: ReferenceAreaHit
      type: object
    ReferenceAreasCheckStatus:
      enum:
        - ok
        - failed
      title: ReferenceAreasCheckStatus
      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
    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

````