PlanOps API

The PlanOps API provides programmatic access to your construction project management data. Build integrations, automate workflows, and create custom applications on top of the PlanOps platform.

API Endpoints

Base URLs

• API Base URL: https://api.planops.ai

Documentation

• API Reference: /api/public/docs - Interactive Swagger UI
• ReDoc: /api/public/redoc - Alternative documentation view
• OpenAPI Schema: /api/public/openapi.json - Machine-readable schema

Quick Start

# 1. Get your token (see Authentication guide)
TOKEN="your_clerk_jwt_token"

# 2. Make your first request
curl https://api.planops.ai/api/v1/projects \
  -H "Authorization: Bearer $TOKEN"

→ Full Getting Started Guide

Key Features

🔐 Authentication

Secure authentication using Clerk-issued JWT tokens. Works seamlessly with web, mobile, and backend integrations.

→ Authentication Guide

📚 Comprehensive API

Access all PlanOps features programmatically:

• Projects - Create, update, and manage projects
• Tasks - Task management and tracking
• Documents - Upload, download, and search documents
• Reports - Generate custom reports and analytics
• Search - Full-text search across your data
• Organizations - Manage teams and permissions

🚀 RESTful Design

Standard HTTP methods, JSON payloads, and predictable resource-oriented URLs:

GET    /api/v1/projects       # List projects
POST   /api/v1/projects       # Create project
GET    /api/v1/projects/{id}  # Get project details
PATCH  /api/v1/projects/{id}  # Update project
DELETE /api/v1/projects/{id}  # Delete project

📖 OpenAPI Schema

Full OpenAPI 3.0 specification for automatic client generation:

# Generate TypeScript client
npx openapi-typescript https://api.planops.ai/api/public/openapi.json \
  --output planops-api.ts

# Generate Python client
openapi-generator-cli generate \
  -i https://api.planops.ai/api/public/openapi.json \
  -g python \
  -o ./planops-client

Common Use Cases

Project Automation

Automate project creation, task assignment, and status tracking:

# Create project with tasks
project = create_project(name="New Build", status="active")
create_tasks(project_id=project['id'], tasks=[
    {"title": "Site Survey", "priority": "high"},
    {"title": "Permits", "priority": "high"},
])

Document Management

Bulk upload, organize, and sync documents:

# Upload construction drawings
for drawing in drawings_folder.glob('*.pdf'):
    upload_document(
        project_id=project_id,
        file=drawing,
        document_type='drawing'
    )

Reporting & Analytics

Extract data for custom reports and dashboards:

# Generate weekly progress report
projects = get_projects(status='active')
for project in projects:
    tasks = get_tasks(project_id=project['id'])
    completion = calculate_completion_rate(tasks)
    send_report(project, completion)

Third-Party Integrations

Connect PlanOps with other construction tools:

# Sync to external CDE
docs = get_documents(project_id=project_id, synced=False)
for doc in docs:
    upload_to_cde(doc)
    mark_as_synced(doc['id'])

→ See Full Workflow Examples

API Guides

Guide	Description
Authentication	Learn how to obtain and use JWT tokens
Getting Started	Make your first API call in 5 minutes
Common Workflows	Real-world integration examples

API Reference

Explore the complete API reference with interactive documentation:

• Swagger UI - Test API calls directly in your browser
• ReDoc - Read-friendly documentation

Available Resources

• Projects - /api/v1/projects
• Tasks - /api/v1/tasks
• Documents - /api/v1/documents
• Reports - /api/v1/reports
• Search - /api/v1/search
• Organizations - /api/v1/organizations

Best Practices

1. Token Management

Always get fresh tokens and handle expiration:

const { getToken } = useAuth();
const token = await getToken(); // Auto-refreshed

2. Error Handling

Handle API errors gracefully:

try:
    response = api_call('/api/v1/projects')
except HTTPError as e:
    if e.status_code == 401:
        refresh_token()
    elif e.status_code == 429:
        wait_and_retry()
    else:
        log_error(e)

3. Rate Limiting

Respect rate limits (100 requests/minute):

# Check rate limit headers
remaining = response.headers['X-RateLimit-Remaining']
if int(remaining) < 10:
    time.sleep(1)  # Slow down

4. Pagination

Use pagination for large datasets:

def get_all_projects():
    page = 1
    while True:
        data = get_projects(page=page, page_size=50)
        yield from data['items']
        if len(data['items']) < 50:
            break
        page += 1

Rate Limits

Limit	Value
Requests per minute	100
Requests per hour	5,000
Concurrent requests	10

Headers returned with each request:

• X-RateLimit-Limit - Request limit
• X-RateLimit-Remaining - Remaining requests
• X-RateLimit-Reset - Reset timestamp

Versioning

The API uses URL-based versioning:

• Current: /api/v1/
• Future: /api/v2/ (when available)

We maintain backward compatibility for at least 12 months when introducing breaking changes.

Support

Resources

• API Reference - Full endpoint documentation
• Guides - Integration tutorials
• Clerk Docs - Authentication help

Get Help

• Technical issues? Check the API Reference for endpoint details
• Authentication problems? Review the Authentication Guide
• Integration support? Contact us through your dashboard

Example Projects

Python Integration

from planops_client import PlanOpsClient

client = PlanOpsClient(token=get_clerk_token())

# List projects
projects = client.projects.list()

# Create task
task = client.tasks.create(
    project_id="proj_123",
    title="Review drawings",
    priority="high"
)

# Upload document
with open('plan.pdf', 'rb') as f:
    doc = client.documents.upload(
        project_id="proj_123",
        file=f,
        title="Site Plan"
    )

JavaScript Integration

import { PlanOpsAPI } from '@planops/sdk';

const api = new PlanOpsAPI({ getToken: () => clerk.getToken() });

// Fetch projects
const projects = await api.projects.list();

// Create task
const task = await api.tasks.create({
  projectId: 'proj_123',
  title: 'Review drawings',
  priority: 'high'
});

// Upload document
const doc = await api.documents.upload({
  projectId: 'proj_123',
  file: fileInput.files[0],
  title: 'Site Plan'
});

Changelog

2025-12-12

• Added public API documentation endpoints
• Published authentication guide with Clerk integration
• Released getting-started and workflow guides

---

Ready to get started? Check out the Getting Started Guide or dive into the API Reference.