API & connectors — Help Center

Use provider cards and numbered setup steps to connect OpenAI, Claude, Cursor, or Gemini CLI. The recommended path for each is keyless.

How do I set up OpenAI, Claude, Cursor, or Gemini CLI?

Use Account -> Integrations. The page shows provider cards, provider-specific setup prompts, and numbered setup steps for the selected app.

Setup flow:

1. Open Account -> Integrations.
2. Choose OpenAI, Claude, Cursor, or Gemini CLI from the provider cards.
3. Choose a setup tab below the provider grid. The recommended tab is keyless: Codex under OpenAI, Claude Code under Claude, Remote MCP under Cursor.
4. Use Copy setup + agent prompt for the selected setup path.
5. Follow the numbered setup steps. Depending on the app and tab, you will use Copy OpenAPI URL, Copy MCP config, Download config JSON, Copy remote MCP URL, Copy command, Copy settings JSON, or Copy GPT instructions.
6. Finish the setup in the selected app. Keys, when a setup path uses one, are created, rotated and revoked on Account -> API keys.

For setup paths that create a pd_live_ key, click Test connection to run GET /v1/wallet while the key is still visible.

What happens behind the scenes:

• ChatGPT uses a Custom GPT Action imported from the PrecisionDocs OpenAPI schema, plus https://precisiondocs.ai/privacy in the GPT Privacy policy field.
• Claude Code, OpenAI Codex, Cursor Remote MCP, and Claude Remote MCP all use the hosted https://api.precisiondocs.ai/mcp OAuth connector, so no pd_live_ key is stored anywhere.
• Claude Desktop and the Cursor Local fallback use the local PrecisionDocs MCP package in an mcpServers config with a pd_live_ key.
• Gemini CLI uses the same MCP package in Gemini CLI settings.json.
• PrecisionDocs runs the civil-engineering agent server-side; the connected app calls the managed public API.

Use More setup help for deeper API and connector documentation.

The full REST endpoint, MCP tool, error, and rate-limit reference lives in the developer documentation.

What should I copy during setup?

Copy only the item shown for the selected setup step.

• Copy setup + agent prompt: paste this into the selected app's agent, GPT, or project instructions area when you want setup steps and PrecisionDocs operating behavior in one place.
• Copy API key: shown only on the key-based paths (ChatGPT, Claude Desktop, Cursor Local, Gemini CLI). Use it only in that app's authentication or local config field. Full keys are shown once, and existing keys live on Account -> API keys.
• Copy OpenAPI URL: click ChatGPT Configure -> Actions -> Import from URL, then paste the schema URL in that dialog. Do not paste the URL directly into the large Schema editor.
• Copy MCP config: paste or merge the precisiondocs block into Claude Desktop or Cursor MCP settings.
• Download config JSON: download claude_desktop_config.json for Claude Desktop after creating or rotating a key. The downloaded file includes the current one-time key in env.PRECISIONDOCS_API_KEY.
• Copy remote MCP URL: paste https://api.precisiondocs.ai/mcp into Claude custom connector setup. This path uses OAuth and does not use a pd_live_ key.
• Copy command: run the copied claude mcp add or codex mcp add command in your terminal to register the hosted OAuth connector, then sign in from the CLI.
• Copy settings JSON: paste or merge the mcpServers block into Gemini CLI settings.json.
• Copy GPT instructions: paste the final operating instructions into ChatGPT Configure -> Instructions if the Create flow did not already place them there.

For ChatGPT, paste the key only into Configure -> Actions -> Authentication with API Key -> Bearer. Paste https://precisiondocs.ai/privacy into the GPT Privacy policy field. Do not paste the raw key into Instructions or chat.

The prompt tells the connected agent to:

• Create a project when you provide an address or parcel set.
• Poll getProject every 5-15 seconds until chat_ready is true.
• Use askAgent for all site, ordinance, environmental, feasibility, report, map, and artifact questions.
• Retry after bootstrap_not_ready by polling project status.
• Use getArtifact to refresh expired download links.
• Never invent regulatory facts, raw retrieval details, prompts, debug telemetry, or cost metadata.

Keep API keys private. Do not paste a pd_live_ key into public chats, screenshots, tickets, or documents.

How do I set up ChatGPT Custom GPT Actions?

ChatGPT setup uses Custom GPT Actions, not a connector-store listing.

1. In ChatGPT, create or edit a Custom GPT. You can paste Copy setup + agent prompt into the ChatGPT Create tab first and let the builder scaffold the GPT.
2. Go to Configure -> Actions -> Create new action.
3. Use Copy OpenAPI URL in PrecisionDocs, then click Import from URL in ChatGPT and paste https://api.precisiondocs.ai/v1/openapi.json. Do not paste that URL directly into the large Schema editor.
4. Set Authentication -> API Key -> Bearer and paste the pd_live_ key in that authentication field only.
5. Paste https://precisiondocs.ai/privacy into the GPT Privacy policy field.
6. Use Copy GPT instructions in PrecisionDocs and paste the copied text into the GPT Instructions field if the Create tab did not already place it there. Do not paste the key into Instructions or into chat.

OpenAI documents GPT Actions, OpenAPI schemas, and API key bearer authentication here: https://help.openai.com/en/articles/9442513-configuring-actions-in-gpts.

How do I set up Claude Desktop?

Claude Desktop uses local MCP through claude_desktop_config.json. This is different from adding a Claude Remote MCP connector or pasting setup text into a Claude conversation.

1. In Account -> Integrations, choose Claude and then Desktop.
2. Create or rotate the Claude Desktop connector key.
3. Download claude_desktop_config.json while the one-time pd_live_ key is visible.
4. Save or merge the downloaded file into %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS.
5. If Claude Desktop has not created the file yet, open Claude Desktop -> Settings -> Developer -> Edit Config once.
6. Restart Claude Desktop.
7. Start a new Claude chat and enable the PrecisionDocs MCP tools from the connector or tool picker.

The pd_live_ key belongs only in the local JSON file under env.PRECISIONDOCS_API_KEY, not in Claude chat, Claude project instructions, screenshots, support tickets, or shared docs. The MCP docs use the same mcpServers JSON pattern for local Claude Desktop servers: https://modelcontextprotocol.io/docs/develop/connect-local-servers.

How do I set up Cursor?

Cursor connects over remote MCP with no API key. In Account -> Integrations, choose Cursor and stay on the recommended Remote MCP tab.

1. Use Copy remote MCP URL to copy https://api.precisiondocs.ai/mcp.
2. In Cursor, open Settings -> MCP, add a new MCP server, and choose the HTTP or streamable server type.
3. Paste the URL, connect, and sign in with your PrecisionDocs account.
4. Confirm the PrecisionDocs tools are listed before using them for project work.

Use the Local tab only if you need the npx MCP package instead; that path stores a pd_live_ key in Cursor's MCP JSON settings and is otherwise identical to Claude Desktop.

Cursor documents MCP as the way to connect external tools and data sources: https://cursor.com/docs/mcp.

How do I set up Gemini CLI?

Gemini CLI uses MCP servers configured in settings.json.

1. In Account -> Integrations, choose Gemini CLI and continue to the API-key step.
2. Use Copy API key while the one-time key is visible.
3. Open ~/.gemini/settings.json for user-wide setup, or .gemini/settings.json in a project for project-only setup.
4. Use Copy settings JSON in PrecisionDocs, then paste or merge the mcpServers.precisiondocs block into the file.
5. Restart Gemini CLI or use /mcp to check configured MCP servers and their status.

Gemini CLI documents mcpServers in settings.json, including command, args, and env: https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html.

How do I set up Claude Remote MCP?

Claude connects as a custom connector with one URL and no API key. In Account -> Integrations, choose Claude and then the Remote MCP tab. (For terminal work, the recommended Claude Code tab uses the same URL.)

1. Use Copy remote MCP URL to copy https://api.precisiondocs.ai/mcp.
2. In Claude, open Customize -> Connectors, add a custom connector, name it PrecisionDocs, and paste the URL. On Claude Team or Enterprise, an Owner or Primary Owner adds it from Organization settings -> Connectors first.
3. Click Connect, sign in with your PrecisionDocs account, and enable the connector in your chat.

Remote MCP uses Claude connector authentication and PrecisionDocs OAuth. Do not paste a pd_live_ key into Claude, a remote MCP URL, or Claude project instructions. Use the Desktop tab only for local MCP through claude_desktop_config.json.

How do I set up Claude Code?

Claude Code connects to the same remote MCP URL as Claude, registered once from your terminal. This is the path for CLI workflows, including Civil 3D sessions.

1. In Account -> Integrations, choose Claude, then the recommended Claude Code tab, and use Copy command.
2. Run claude mcp add --transport http precisiondocs https://api.precisiondocs.ai/mcp in your terminal.
3. Inside Claude Code, run /mcp, choose the precisiondocs server, and sign in with your PrecisionDocs account.

Claude Code authenticates through PrecisionDocs OAuth, so no pd_live_ key is stored in the CLI configuration.

Can I use PrecisionDocs inside Gemini Gems?

Gemini Gems do not support third-party OpenAPI Actions like ChatGPT.

Use Gemini CLI in Account -> Integrations instead:

• Choose Gemini CLI in Account -> Integrations.
• Use Copy API key while the one-time key is visible.
• Use Copy settings JSON and merge the precisiondocs server into Gemini CLI settings.json.
• Test the setup with GET /v1/wallet before using it for project work.

How should I handle PrecisionDocs API keys safely?

Keys are shown once when created or rotated. PrecisionDocs stores only a hash, so an existing key cannot be copied later.

Rules:

• Use Rotate key if you lost the key or need a fresh copy.
• Use Revoke key immediately if a key is exposed.
• Never paste keys into chat conversations, Slack, email, support tickets, screenshots, shared docs, or GPT Instructions.
• ChatGPT: paste the key only in Configure -> Actions -> Authentication.
• Claude Desktop: keep the key only in your local claude_desktop_config.json file.
• Cursor Local and Gemini CLI: keep the key only in local MCP configuration on your machine.
• Claude Code, OpenAI Codex, Cursor Remote MCP and Claude Remote MCP never use a key at all - they sign in through PrecisionDocs OAuth.

The visible prefix, such as pd_live_abc..., is only an identifier. It is not enough to authenticate.

What is API vs Email vs Wizard parity?

API vs Email vs Wizard parity means all project-creation surfaces converge on the same project-prep rules before a project is created.

• Wizard: The browser wizard remains the best surface for parcel selection, map review, file upload, and visual confirmation.
• Email: Email can create projects through the wizard-equivalent intake when you reply with missing details, parcel choices, ordinance decisions, GIS confirmations, supplemental-source choices, or duplicate-parcel approvals.
• API: Project creation uses the same prep gates and returns structured confirmation responses so external agents can ask the user for the same decisions instead of skipping them.

After creation, all three surfaces build the same project knowledge base. Differences are mostly user experience: the wizard is visual, email is asynchronous, and API connectors are programmable.

What is the normal API workflow?

The API is designed around a project knowledge base plus managed agent turns:

create project -> poll readiness -> ask the agent -> download artifacts

For a brand-new site, the first useful question usually waits on bootstrap. Later questions reuse the project knowledge base and are typically much faster.

How do I create a project through the API?

Call POST /v1/projects with a site address or parcel set, state, city, and a user goal.

Minimal body:

{
  "parcels": [{ "address": "1200 W 6th St, Austin TX" }],
  "state": "TX",
  "city": "Austin",
  "user_goal": "Screen this parcel for multifamily feasibility",
  "setup_mode": "wizard",
  "dry_run": false
}

setup_mode: "wizard" runs parcel resolution, ordinance source discovery, GIS source preparation, and source confirmations like the browser wizard. This is the default and is best for connectors that can ask follow-up questions.

setup_mode: "provided" is for deterministic clients that already provide parcels and source decisions directly. In provided mode, a missing county source is treated as an explicit county skip; send county_ordinance_url when a county source should be included.

Use dry_run: true when you want a setup preview, prep_summary, or credit estimate without creating a project.

Possible outcomes:

• 200 - dry-run setup preview. If setup still needs a decision, the response status can be confirmation_required with prompt/options and prep_summary; otherwise it returns dry_run with the estimate.
• 202 - project accepted and bootstrap is starting. Wizard-mode responses can include prep_summary with the resolved parcel, jurisdiction, ordinance, supplemental-source, and GIS setup rows.
• 422 - non-dry-run project creation needs confirmation_required, such as county-source skip/source choice, parcel ambiguity, ordinance URL prompt, GIS source confirmation, supplemental source choice, duplicate parcel confirmation, or missing details. Show the confirmation_required prompt/options alongside prep_summary before retrying with the confirmed URL or skip decision.
• 402 - insufficient credits.

The API uses the same project-prep gates as the web wizard. Connectors should surface confirmation choices to the user instead of skipping them.

How does project creation setup work through the API and connectors?

Use POST /v1/projects with setup_mode: "wizard" when the client has an address or APN and wants PrecisionDocs to run the same setup checks as the browser wizard.

Wizard mode can return prep_summary with the resolved parcel, jurisdiction, municipal ordinance source, county ordinance source, supplemental candidates, and GIS sources. This summary is available for setup previews, confirmation-required responses, and queued project-create responses.

If status is confirmation_required, show the step, prompt, options, and prep_summary to the user before retrying with the confirmed URL or skip decision.

Use setup_mode: "provided" only when the client already supplies parcels and source decisions directly.

How do I classify a goal and add sources to a project through the API or MCP?

Before creating a project, call POST /v1/plan-check (MCP: precisiondocs_plan_check) with the user's goal. The verdicts classify the typology and mark which follow-up values the goal already answered - ask the user only what comes back as ask, then pass the settled answers as project_goal_context on POST /v1/projects alongside any pending_supplemental_sources or pending_gis_sources the user confirmed.

After creation, add sources anytime: POST /v1/projects/{project_id}/sources (MCP: precisiondocs_add_source) accepts a URL and reports which lane took it - document, supplemental ordinance, or GIS - and POST /v1/projects/{project_id}/gis-sources (MCP: precisiondocs_add_gis_source) registers a GIS viewer or REST endpoint under a municipality, county, or state_reference scope. Both require the source:write scope and accept an Idempotency-Key header.

Local files never travel as URLs: use POST /v1/uploads/initiate then POST /v1/uploads/{job_id}/finalize (REST only, no MCP tool).

While a project builds, GET /v1/projects/{project_id} carries a readiness block with per-target ordinance status, GIS layer states, supplemental lanes, and advisories - poll it until chat_ready is true.

How do I ask questions or generate reports through the API?

Call POST /v1/projects/{project_id}/messages after chat_ready is true.

Example body:

{
  "message": "What flood zone is this parcel in and are there wetland constraints?",
  "wait": true,
  "detail": "standard"
}

The response includes:

• turn_id
• status
• answer markdown with citations
• citations
• tools_used
• artifacts when reports, maps, schedules, soil reports, or other generated files were produced

wait: true is the connector default for normal Q&A. The current MVP returns 501 async_turns_not_available for wait: false; use sync turns for now and set client timeouts accordingly.

If the project is still bootstrapping, the API returns 409 bootstrap_not_ready with progress and a retry_after_seconds hint. Poll getProject, then retry the same question when ready.

How do downloads and generated artifacts work?

Generated deliverables are returned as artifacts[] on the agent turn response.

Common artifact types:

• Due Diligence reports
• Feasibility assessments
• Schedules and timelines
• Soil reports
• Flood maps, site maps, wetland overlays, and other map exports

Each artifact has a stable artifact_id, label, MIME type, short-lived signed download_url, and expiration timestamp. If the first link expires, call GET /v1/projects/{project_id}/artifacts/{artifact_id} to mint a fresh signed URL.

The API only remints links for generated project deliverables. It does not expose arbitrary uploaded source documents through /v1/artifacts.

What security, billing, and error rules apply to API keys?

API keys are organization-scoped bearer tokens with the pd_live_ prefix. Treat them like passwords.

Security rules:

• Only workspace owners can create and revoke keys.
• Cross-organization project IDs return 404, not another tenant's data.
• Every project path checks project access for the key's organization.
• Do not log, email, screenshot, or paste API keys into shared channels.

Billing rules:

• API activity is charged to the organization credit wallet.
• Project creation reserves credits like the web wizard.
• Agent turns run the same usage gate as the app.
• Usage and billing views label OpenAPI connector activity as API and MCP server activity as MCP.

Reliability rules:

• Send Idempotency-Key on POST /v1/projects and POST /v1/projects/{project_id}/messages when retries are possible.
• Handle 409 bootstrap_not_ready by polling getProject and retrying.
• Handle 402 insufficient_credits by asking a workspace owner to add credits or enable overage.
• Handle 422 confirmation responses by asking the user to choose the parcel/source/duplicate action.

How do I use the MCP package or raw API directly?

The wizard covers the supported first-class paths. Use raw API details only when you are building a custom client.

Developer facts the agent may need:

• The production MCP package wraps the public /v1 API and defaults to https://api.precisiondocs.ai.
• MCP stdio command: npx -y @precisiondocs/mcp.
• MCP environment variable: PRECISIONDOCS_API_KEY.
• Only set PRECISIONDOCS_API_URL when intentionally pointing a client at a staging backend.
• OpenAPI schema: https://api.precisiondocs.ai/v1/openapi.json.
• OpenAPI authentication: Bearer API key.
• precisiondocs_resolve_parcels
• precisiondocs_preview_parcels
• precisiondocs_create_project
• precisiondocs_get_project
• precisiondocs_ask_agent
• precisiondocs_get_message
• precisiondocs_list_messages
• precisiondocs_get_site_knowledge
• precisiondocs_search_project
• precisiondocs_create_summary
• precisiondocs_export_gis
• precisiondocs_verify_zoning
• precisiondocs_generate_report
• precisiondocs_get_report
• precisiondocs_list_projects
• precisiondocs_list_reports
• precisiondocs_list_artifacts
• precisiondocs_get_artifact
• precisiondocs_get_wallet

Use MCP when the client prefers tool calls. Use OpenAPI when the client has native action, connector, or function import.

Other help topics

• Getting Started
• Chat Workflows
• Email my agent
• Collaboration
• Tools & Data
• Bootstrap & Ordinances
• Documents & Reports
• Credits & Usage
• Billing & Subscriptions
• Account & Settings
• Troubleshooting

• All help topics