Plan Check, Sources & Uploads — Developer Docs
Classify a goal before creation, then attach URL sources, GIS sources, and file uploads to a project.
How do I classify a goal and attach sources to a project?
All five endpoints require the source:write scope except plan check, which uses project:create. Source and upload writes accept an Idempotency-Key header so a retry never double-ingests.
| Endpoint | What it does | Scope | Rate limit |
|---|---|---|---|
POST /v1/plan-check | Classifies goal text into a typology and reports which follow-up values the goal already answers | project:create | 20/min |
POST /v1/projects/{project_id}/sources | Adds a URL source; the response names the lane that accepted it (document, supplemental ordinance, or GIS) | source:write | 10/min |
POST /v1/projects/{project_id}/gis-sources | Registers a user-verified GIS source by authority scope | source:write | 10/min |
POST /v1/uploads/initiate | Starts a file-upload job for a local document | source:write | 30/min |
POST /v1/uploads/{job_id}/finalize | Finalizes an initiated upload into the project knowledge base | source:write | 30/min |
Plan check (POST /v1/plan-check): send { goal_text, primary_typology?, has_existing_structure? }. The verdicts in the response tell your agent which follow-up values the goal already settled and which come back as ask. Ask the user only the ask items, then pass the settled answers as project_goal_context on POST /v1/projects.
URL sources (POST .../sources): send { url, title?, category? }. The response reports which ingest lane accepted the URL - a project document, a supplemental ordinance corpus, or a GIS source - so your client can say what will happen next.
GIS sources (POST .../gis-sources): send { url, scope, jurisdiction_name? } where scope is municipality, county, or state_reference. Use it for a viewer or ArcGIS REST endpoint the jurisdiction publishes that discovery did not find.
File uploads: local files never travel as URLs. Call POST /v1/uploads/initiate, upload the bytes as directed, then call POST /v1/uploads/{job_id}/finalize. The MCP server does not wrap uploads - URL sources only.
Sources at creation: POST /v1/projects also accepts pending_supplemental_sources (max 10: url, title, category, authority_scope) and pending_gis_sources (max 6: url, scope, jurisdiction_name) so a connector can hand over everything the user confirmed in one create call.