API Pluia public-api/1

GET/

Point d'entrée de l'API

Sans clé.

GET/openapi.json

Contrat OpenAPI 3.1

Sans clé.

GET/docs

Documentation lisible

Sans clé.

GET/me

Ma clé, mon offre et mes quotas

Quotas lus comme l'écran Abonnement (mêmes chiffres).

Portée : read.

Réponse 200 :

{
    "key": {
        "public_id": "a1b2c3d4",
        "name": "Cursor",
        "environment": "live",
        "scopes": [
            "read",
            "studio"
        ],
        "expires_at": "2027-10-07T00:00:00Z",
        "rate_limit_per_minute": 120,
        "daily_consumption_cap": 20
    },
    "account": {
        "plan": "pro",
        "plan_label": "Pro",
        "email_verified": true
    },
    "quotas": {
        "dossiers": {
            "used": 3,
            "limit": 20,
            "remaining": 17,
            "unlimited": false
        }
    },
    "period": {
        "scope": "billing_period",
        "start": "2026-10-01T00:00:00Z",
        "end": "2026-10-31T23:59:59Z"
    }
}

GET/parcels/search

Trouver une parcelle

Exactement un moyen : address, idu, insee+section+number (+prefix), ou lat+lon. Un point hors de toute parcelle donne les parcelles les plus proches, jamais présentées comme certaines.

Portée : read.

Réponse 200 :

{
    "query": {
        "idu": "91312000AE0290"
    },
    "candidates": [
        {
            "idu": "91312000AE0290",
            "insee": "91312",
            "commune": "Igny",
            "prefix": "000",
            "section": "AE",
            "number": "0290",
            "parcel_ref": "AE-0290",
            "area_m2": 563,
            "address": null,
            "locality": "Igny",
            "reference_point": {
                "lat": 48.73697,
                "lon": 2.22066
            },
            "match": "idu_exact",
            "geocoder_score": null
        }
    ],
    "sources": [
        {
            "name": "API Carto – cadastre (IGN)",
            "url": "https://apicarto.ign.fr/api/cadastre/parcelle"
        }
    ],
    "warnings": []
}

GET/parcels/{idu}

Une parcelle avec sa géométrie

Portée : read.

GET/parcels/{idu}/zoning

Zonage PLU d'une parcelle

Zone au point de référence (moyenne des sommets, point intérieur si elle tombe hors de la parcelle), zones qui traversent la parcelle avec leur part de surface, document du Géoportail, état de l'index et version du règlement indexé.

Portée : read.

GET/parcels/{idu}/constraints

Servitudes, prescriptions et patrimoine

Une liste vaut « unavailable » quand sa source n'a pas répondu, « partial » quand une couche manque : jamais « aucune » par défaut.

Portée : read.

GET/communes/{insee}/regulation

État du règlement d'une commune

Lecture seule : ne déclenche jamais d'indexation (la création d'un dossier le fait, comme dans l'application).

Portée : read.

GET/documents/{document_id}

État d'un document indexé

Portée : read.

GET/documents/{document_id}/pages/{page}

Texte d'une page du règlement officiel

Documents cités par un de vos dossiers (ou téléversés par vous), 300 pages par jour. Texte de la couche texte du PDF officiel, non retouché ; null si le PDF est scanné ou pas encore extrait (ouvrir pdf_url).

Portée : read.

GET/dossiers

Lister mes dossiers

Portée : read.

POST/dossiers

Créer le dossier PLU d'une parcelle (1 dossier)

Même analyse que l'application (même moteur, même quota, réservation idempotente par parcelle et période). Commune non indexée : 202 indexing, rien décompté. Commune sans PLU (RNU, carte communale, POS) : dossier enregistré, non décompté.

Portée : analyze. Quota : dossiers (même décompte que l’application).

Corps :

{
    "idu": "91312000AE0290"
}

GET/dossiers/{id}

Un dossier

Portée : read.

GET/dossiers/{id}/rules

Règles clés prouvées

Mêmes valeurs, statuts, pages et liens que l'écran Analyse et le rapport PDF. Chaque règle : assertion (statut), is_verified, proof (page, extrait, lien PDF#page=N).

Portée : read.

Réponse 200 :

{
    "dossier_id": "0d8f3c1e-0000-4000-8000-000000000001",
    "zone": "UH",
    "document": {
        "name": "91312_PLU_20231005",
        "approval": "05/10/2023",
        "version_status": "current"
    },
    "versioned": true,
    "key_rules": [
        {
            "id": "emprise_sol",
            "label": "Emprise au sol",
            "state": "value",
            "assertion": "verified",
            "assertion_label": "Vérifié",
            "is_verified": true,
            "value": "40 %",
            "measure": {
                "value": 40,
                "unit": "%"
            },
            "condition": "",
            "to_read": "",
            "reference": {
                "article": "Article UH 9",
                "pages": "p. 87",
                "label": "Article UH 9 · p. 87",
                "href": "https://data.geopf.fr/annexes/gpu/documents/DU_91312/…/91312_reglement_20231005.pdf#page=87"
            },
            "proof": {
                "status": "verified",
                "label": "Vérifié · p. 87",
                "page": 87,
                "excerpt": "L'emprise au sol des constructions ne peut excéder 40 %…",
                "href": "https://data.geopf.fr/…#page=87",
                "figures": [
                    "40 %"
                ],
                "official": true
            }
        }
    ],
    "notice": "Seules les valeurs « Vérifié » (is_verified = true) ont été relues à la page citée du règlement officiel ; elles s’appliquent avec leur condition. Les autres se lisent dans le règlement à la page indiquée.",
    "sources": []
}

GET/dossiers/{id}/regulation-version

Version du règlement servi

Portée : read.

GET/dossiers/{id}/studio-rules

Seuils sourcés pour le Studio et la CAO (studio-rules/1)

Portée : studio.

POST/dossiers/{id}/checks

Vérifier un projet (verdict règle par règle)

Verdict d’un projet (extension, véranda, piscine, garage, abri…) sur les règles du dossier, avec le moteur du Studio : mêmes seuils, mêmes textes que le Studio, l’écran et le PDF. Les mesures sont DÉCLARÉES par l’appelant (aucun plan n’est contrôlé) et le disent dans `warnings`. Une mesure absente reste « Non déterminé » ; sans `existing_footprint_m2`, l’emprise n’est jamais déclarée conforme. Le code de sortie du CLI suit `exit_code` (0 oui, 1 non, 2 sous conditions ou non déterminé). Aucun quota, aucun appel LLM. Même garde d’offre que le Studio ; 503 tant que le moteur n’est pas installé sur le serveur.

Portée : studio.

Corps :

{
    "project_type": "extension",
    "measures": {
        "height_m": 3.5,
        "project_footprint_m2": 30,
        "existing_footprint_m2": 120,
        "street_distance_m": 6,
        "side_distance_m": 4,
        "rear_distance_m": 10,
        "open_ground_m2": 250
    },
    "answers": {
        "facade_openings": false
    }
}

Réponse 200 :

{
    "contract": "pluia-check/1",
    "engine": "rule-eval/1",
    "rules_contract": "studio-rules/1",
    "dossier_id": "0d8f3c1e-5a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "verdict": {
        "code": "conditional",
        "label": "Sous conditions",
        "subtitle": null,
        "detail": "Le verdict dépend de vos précisions sur le projet.",
        "conclusive": false,
        "reasons": [],
        "corrective_actions": []
    },
    "exit_code": 2,
    "checks": [
        {
            "id": "hauteur",
            "family": "hauteur",
            "metric": "height_max",
            "label": "Hauteur maximale",
            "status": "pass",
            "status_label": "Conforme",
            "requirement": "Maximum 10 m",
            "measured": "3,5 m",
            "note": null,
            "confidence": "high",
            "question_ids": [],
            "corrective_action": null,
            "indicative": false,
            "source": {
                "article": "Article UC 10",
                "article_verified": true,
                "page": 88,
                "excerpt": "La hauteur maximale des constructions ne peut excéder 10 mètres.",
                "href": "https://www.geoportail-urbanisme.gouv.fr/api/document/0123/files/reglement.pdf#page=88",
                "document_id": "6b1e0a52-3f4d-4c5b-9a6e-7f8091a2b3c4",
                "assertion": "official_text"
            }
        }
    ],
    "questions": [
        {
            "id": "facade_openings",
            "label": "La façade du projet face à la limite aura-t-elle des fenêtres ou des baies ?",
            "kind": "boolean",
            "decisive": true,
            "options": [
                {
                    "value": true,
                    "label": "Oui"
                },
                {
                    "value": false,
                    "label": "Non"
                }
            ],
            "answer": false
        }
    ],
    "blockers": [
        "Retrait des limites séparatives : répondre à la question sur les baies"
    ],
    "source_status": "ok",
    "warnings": [
        "Mesures déclarées par l’appelant, non contrôlées sur un plan."
    ]
}

POST/dossiers/{id}/report

Rapport PDF du dossier (1 export)

Le rapport de l'application (même modèle que l'écran). Rejeu de la même Idempotency-Key : jamais décompté deux fois. Rendu PDF indisponible : HTML imprimable (Pluia-Report-Format: html).

Portée : report. Quota : pdf_exports (même décompte que l’application).

Corps :

[]

POST/dossiers/{id}/questions

Poser une question sur le règlement (1 question)

Agent PLU de l'application (même moteur de réponse, mêmes citations). Chaque question compte ; un refus motivé est une réponse valide.

Portée : ask. Quota : agent_questions (même décompte que l’application).

Corps :

{
    "question": "Puis-je construire en limite séparative ?"
}