PyProcore

Open-source Python SDK and automation toolkit for safe, read-oriented Procore integrations.

PyProcore helps developers, consultants, and construction-tech teams build Procore integrations without rebuilding OAuth, token refresh, pagination, retries, typed response parsing, downloads, exports, and local automation plumbing from scratch.

The SDK is read-oriented and safety-first. It is designed for listing, retrieving, searching, downloading, exporting, packaging, and validating Procore project data while keeping write and execution surfaces closed by default.

The latest published stable release is 2.3.0. Version 2.4.0 is prepared in this repository but has not yet been published. It adds Project Tools read coverage, local plugin trust policy reports, OAS catalog and discovery metadata, integration blueprints, local analytics, an optional FastAPI starter, and a human-review API maintenance workflow covering drift, impact, migration plans, draft packs, compatibility contracts, and migration guides.

These features remain read-only, local, or report-oriented. MCP is discovery-only, Procore tool execution is disabled, and no external AI/model API is called by default. Maintenance helpers do not fetch remote code/specs, edit customer code, apply patches, run git, call GitHub, or open pull requests.

Installation

Install the current stable release:

python3 -m pip install pyprocore==2.3.0

Install optional async HTTP support:

python3 -m pip install "pyprocore[async]==2.3.0"

The prepared 2.4.0 package is available from this checkout only until manual release publication.

Quick Start

Create and configure a local .env file:

cp .env.example .env

Check your setup and complete OAuth:

procore-sdk doctor
procore-sdk auth login-url
procore-sdk auth exchange-code YOUR_AUTHORIZATION_CODE
procore-sdk companies

Use the object client:

from pyprocore import Procore

client = Procore()

projects = client.projects.list(company_id=123456)
for project in projects:
    print(project.id, project.name)

Build a local project context package:

from pyprocore.workflows import build_project_context_package

result = build_project_context_package(
    project_id=352338,
    company_id=4286480,
    output_dir="exports/project-context",
    include=["project", "rfis", "submittals"],
    max_items=100,
)

print(result.summary_path)

PyProcore loads .env from the current working directory and does not override environment variables that are already set.

What You Can Build

Typed Procore API Access

• Work with typed Pydantic models instead of raw JSON dictionaries.
• Use an object-oriented Procore client or function-style service helpers.
• Rely on automatic pagination, retries, token refresh, and custom SDK errors.

Local Exports And Sync Workflows

• Export supported resources to CSV, JSONL, Markdown, and manifest files.
• Build repeatable local workflow plans for project exports.
• Run dry-run and validation helpers before scheduled automation.

AI-Ready Local Context Packages

• Package RFIs, submittals, documents, drawings, specs, and project context for review workflows.
• Generate local prompt packs, checklists, source indexes, and vector-export manifests.
• Keep model selection outside the SDK; no AI provider is called by default.

Async Read Workflows

• Use AsyncProcore for read-oriented async workflows.
• Export and download with conservative concurrency controls.
• Plan async multi-project batches with local validation and dry-run manifests.

Enterprise Scheduled-Export Planning

• Validate scheduled export configs locally.
• Review token-store safety and credential rotation guidance.
• Use private deployment and production runbook docs for operational planning.

Plugin Metadata And Local Extension Scaffolding

• Inspect metadata-only plugin manifests and extension-pack files.
• Register trusted in-process hooks only from local application code.
• Generate local plugin developer templates without fetching or installing remote plugins.
• Validate local plugin trust policies and metadata-only trust reports without installing, importing, or executing plugin code.

Local OAS Catalog Intelligence

• Inspect a user-provided local OpenAPI/OAS JSON file.
• Classify endpoints as read-only, risky/write, or unknown from metadata.
• Compare endpoint areas to known PyProcore read coverage.
• Compare local specs and plan human-reviewed read-only coverage with the API maintenance assistant.
• Scan a user-selected local codebase for PyProcore usage and relate broad capability families to optional local OAS drift.
• Build human-review migration plans and optional review artifacts without applying patches, running git, or changing customer files.
• Produce JSON or Markdown reports without fetching remote catalogs, generating executable tools, editing customer code, calling Procore, or enabling writes.

Local Discovery Router Metadata

• Search PyProcore capability metadata by intent, such as overdue rfis.
• Get ranked route suggestions with reasons and explicit safety boundaries.
• Include local OAS catalog candidates when a local OAS JSON file is provided.
• Keep discovery metadata-only: no SDK execution, no Procore calls, no MCP execution, no external AI/model calls, no remote OAS fetch, and no writes.

Local Integration Blueprints

• Inspect safe templates for sync workers, webhook receivers, read-only APIs, dashboard data bridges, scheduled exports, and project health feeds.
• Create local sync-run JSON/JSONL records and sanitized webhook fixtures.
• Run local readiness checks for output paths, env vars, token-store placement, webhook secrets, and no-secrets guidance.
• Keep blueprints local-only: no hosted app, no database dependency, no automatic scheduler, no Procore calls, no MCP/tool execution, and no write actions.

Local Project Health Analytics

• Analyze local/exported RFI, submittal, change, and Daily Log records.
• Produce deterministic JSON, Markdown, and CSV summaries for review workflows.
• Combine available signals into a heuristic project health report.
• Keep analytics local-only: no Procore calls, no external AI/model calls, no hosted dashboard, no database dependency, and no write actions.

Optional FastAPI Read API Starter

• Inspect or copy a static FastAPI starter template for read-only backend experiments.
• Keep FastAPI and uvicorn outside PyProcore package dependencies.
• Copy local template files only; no app is hosted, no dependencies are installed, no Procore calls are made, and no write routes are enabled.

Deterministic Evals And Regression Checks

• Run local golden eval suites for workflow packages and manifests.
• Compare deterministic baselines and regression reports.
• Score offline model-response fixtures without calling a model.

MCP Discovery Metadata

• Inspect MCP-style resources, prompts, contracts, snapshots, and reports.
• Inspect the local agent tool registry, local agent API server, agent OpenAPI and JSON Schema exports, and replay metadata.
• Validate discovery metadata locally without credentials.
• Keep MCP discovery separate from tool execution.

See the full feature inventory.

Supported Resource Families

PyProcore supports read-oriented access across these resource families:

• Companies and Projects
• RFIs and Submittals
• Project Tools, Documents, Drawings, Specifications, Photos, and Daily Logs
• Observations, Punch Items, Correspondence, Meetings, Inspections, and Incidents
• Directory, Vendors, Departments, Distribution Groups, and Locations
• Read-only financial, contract, billing, schedule, task, form, coordination issue, and action-plan metadata

See API Coverage for endpoint notes, permission context, and live-verification limitations.

CLI Overview

Common commands:

procore-sdk doctor
procore-sdk companies
procore-sdk projects
procore-sdk rfis --project 352338
procore-sdk submittals --project 352338
procore-sdk project-context --project 352338 --company 4286480
procore-sdk scheduled-export dry-run examples/configs/scheduled_export_client_credentials.json
procore-sdk evals run
procore-sdk mcp validate
procore-sdk catalog summarize examples/catalog/fake_procore_oas.json
procore-sdk discovery search "overdue rfis"
procore-sdk analytics project-health --rfis examples/analytics/fake_rfis.json --format markdown
procore-sdk templates show fastapi-read-api
procore-sdk templates copy fastapi-read-api --output-dir ./tmp-fastapi-read-api --dry-run

See CLI Usage for the full command reference.

Safety Model

PyProcore is intentionally conservative:

• PyProcore is read-oriented.
• Workflow helpers write local files, not Procore data.
• Procore tool execution is disabled.
• MCP is discovery-only.
• No external AI/model APIs are called by default.
• Plugin manifests, configs, extension packs, and scaffolds are metadata or templates only.
• No Procore create, update, delete, upload, approve, submit, payment, or other mutation actions are enabled.

Never commit .env files, OAuth tokens, token stores, Authorization headers, or private project data.

Documentation Site

Topic	Link
Documentation Home	docs/index.md
Getting Started	docs/getting-started.md
Authentication	docs/authentication.md
Complete Feature Inventory	docs/features.md
API Coverage	docs/api-coverage.md
Workflows	docs/workflows.md
Docker Automation	docs/automation/docker.md
CI Automation	docs/automation/ci.md
Docker Examples	examples/docker
Async Client	docs/async-client.md
AI Workflows	docs/ai-workflows.md
Agent API	docs/agent-api.md
MCP Discovery	docs/mcp.md
Plugins	docs/plugins.md
Analytics Recipes	docs/analytics-recipes.md
FastAPI Starter	docs/fastapi-starter.md
Golden Evals	docs/evals.md
Release Guide	docs/release.md
Roadmap	docs/roadmap.md
Features	docs/features.md
Examples	examples/README.md
Project Status	docs/project-status.md
GitHub Labels	docs/github-labels.md

Run make docs-build to build the MkDocs site or make docs-serve to preview it locally.

Prepared For v2.4.0

v2.4.0 is an additive, backward-compatible release candidate. Highlights:

• Read-only Project Tools metadata helpers.
• Local plugin trust policies and compatibility reports.
• Local OAS catalog, discovery routing, integration blueprints, analytics recipes, and an optional copied FastAPI starter.
• Human-review API drift, codebase impact, migration planning, PR draft, compatibility contract, and migration-guide reports.
• Examples through 334 and corresponding mocked/local tests.

Detailed release history lives in CHANGELOG.md, Project Status, and Roadmap.

Contributing and Support

Contributions, issues, and feature requests are welcome. Start with CONTRIBUTING.md, SUPPORT.md, SECURITY.md, and CODE_OF_CONDUCT.md.

Security

Do not paste or commit Procore client secrets, access tokens, refresh tokens, Authorization headers, .env files, token stores, or private project data. See SECURITY.md and docs/security.md.

Maintainers can run make secret-check and make quality-check before release or documentation changes.

License

PyProcore is released under the MIT license.

Disclaimer

PyProcore is an independent open-source project. It is not affiliated with, endorsed by, or supported by Procore Technologies. For official Procore product support, use Procore's support channels.