Skip to main content
API docs by Redocly

PlanOps Public API (1.0.0)

Download OpenAPI specification:Download

Public API for PlanOps construction project management

API Response Data

Response Data Schemas

Common response data structures used across the API.

API Usage Tags

API Usage & Monitoring

Track API usage and access patterns.

Downloads

File Downloads

Download files and documents from the system.

File Upload

File Uploads

Upload files to the system with presigned URLs.

Upload Flow:

  1. Request a presigned upload URL
  2. Upload file directly to cloud storage using the URL
  3. Confirm the upload to register the file

docs-export

Documentation Export

Export app-wide agents and tasks for documentation generation.

This API provides structured data about all agents and their app-wide tasks in formats suitable for documentation systems. The export excludes organization and project-specific tasks.

Features:

  • Export all agents with their app-wide tasks
  • JSON and YAML output formats
  • Includes input/output schemas for each task
  • Workflow step summaries
  • Example inputs/outputs for documentation
  • Cache headers for efficient polling

Use Cases:

  • Generate static documentation for external repositories
  • Build dynamic help systems
  • Create API client libraries
  • Power developer tools with autocomplete

Export app-wide agents and tasks for documentation

Export all agents and their app-wide tasks in a documentation-friendly format.

This endpoint returns structured data about all agents and their tasks that are defined at the app level (not organization or project specific). The data is suitable for generating user documentation, API references, or integration with documentation systems.

Scope:

  • Only includes tasks where organization_id and project_id are both null
  • Organization and project-specific tasks are excluded
  • All active agents are included

Use Cases:

  1. Generate static documentation for the planops-docs repository
  2. Build dynamic help systems that show available agent capabilities
  3. Create API client libraries that understand task schemas
  4. Power autocomplete/intellisense in developer tools

Response Format: The response includes:

  • metadata: Export timestamp, counts, and version info
  • agents: List of agents with their tasks, input/output schemas, and workflows

Caching: The response includes cache headers. Documentation typically doesn't change frequently, so clients can cache this response for several minutes.

header Parameters
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "agents": [
    ]
}

Export app-wide agents and tasks for documentation

Export all agents and their app-wide tasks in a documentation-friendly format.

This endpoint returns structured data about all agents and their tasks that are defined at the app level (not organization or project specific). The data is suitable for generating user documentation, API references, or integration with documentation systems.

Scope:

  • Only includes tasks where organization_id and project_id are both null
  • Organization and project-specific tasks are excluded
  • All active agents are included

Use Cases:

  1. Generate static documentation for the planops-docs repository
  2. Build dynamic help systems that show available agent capabilities
  3. Create API client libraries that understand task schemas
  4. Power autocomplete/intellisense in developer tools

Response Format: The response includes:

  • metadata: Export timestamp, counts, and version info
  • agents: List of agents with their tasks, input/output schemas, and workflows

Caching: The response includes cache headers. Documentation typically doesn't change frequently, so clients can cache this response for several minutes.

header Parameters
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "agents": [
    ]
}

Export app-wide agents and tasks as YAML

Export all agents and their app-wide tasks in YAML format.

This is the same data as the JSON endpoint but formatted as YAML for direct use in documentation repositories or configuration files.

The YAML output is human-readable and can be directly committed to documentation repositories like planops-docs.

query Parameters
indent
integer (Indent) [ 1 .. 8 ]
Default: 2

YAML indentation level

header Parameters
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response samples

Content type
null

Export app-wide agents and tasks as YAML

Export all agents and their app-wide tasks in YAML format.

This is the same data as the JSON endpoint but formatted as YAML for direct use in documentation repositories or configuration files.

The YAML output is human-readable and can be directly committed to documentation repositories like planops-docs.

query Parameters
indent
integer (Indent) [ 1 .. 8 ]
Default: 2

YAML indentation level

header Parameters
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response samples

Content type
null

Export a single agent and its app-wide tasks

Export a specific agent and its app-wide tasks for documentation.

Use this endpoint when you only need documentation for a single agent, such as when generating agent-specific help pages.

path Parameters
agent_id
required
string (Agent Id)
header Parameters
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response samples

Content type
application/json
{ }

Export a single agent and its app-wide tasks

Export a specific agent and its app-wide tasks for documentation.

Use this endpoint when you only need documentation for a single agent, such as when generating agent-specific help pages.

path Parameters
agent_id
required
string (Agent Id)
header Parameters
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response samples

Content type
application/json
{ }

documents

Document Management

Manage construction documents including drawings, specifications, contracts, and other project files.

Features:

  • Upload and store documents with automatic metadata extraction
  • AI-powered document analysis and summarization
  • Full-text search across document content
  • Version tracking and revision history
  • Document classification and tagging

Create Document

Create a new document.

Args:

document: Document data to create
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Created document

Raises:

HTTPException: If project or organization not found, or user not authorized
Authorizations:
HTTPBearer
Request Body schema: application/json
required
document_id
required
string (Document Id)

Document ID

Title (string) or Title (null) (Title)

Document title

Document Reference (string) or Document Reference (null) (Document Reference)

Document reference or drawing number

Description (string) or Description (null) (Description)

Document description

DocumentStatus (string) or null

Document status

Revision (string) or Revision (null) (Revision)

Document revision

Category (string) or Category (null) (Category)

Document category

DocumentType (string) or null

Type of document

Content (string) or Content (null) (Content)

Extracted text content from document

Summary (string) or Summary (null) (Summary)

Summary of document

Purpose (string) or Purpose (null) (Purpose)

Purpose of document

Array of Keywords (strings) or Keywords (null) (Keywords)
Default: []

Keywords associated with document

File Path (string) or File Path (null) (File Path)

Path to stored document

File Size (integer) or File Size (null) (File Size)

Size of document in bytes

Mime Type (string) or Mime Type (null) (Mime Type)

MIME type of document

created_at
string <date-time> (Created At)

Creation timestamp

updated_at
string <date-time> (Updated At)

Last update timestamp

Array of objects (Version History)

Version history of document

Thumbnail Image Path (string) or Thumbnail Image Path (null) (Thumbnail Image Path)

Path to thumbnail image

Full Image Path (string) or Full Image Path (null) (Full Image Path)

Path to full image

Error (string) or Error (null) (Error)

Error message if document processing failed

Error Detail (object) or Error Detail (null) (Error Detail)

Error details

filename
required
string (Filename)

Filename of document

r2_path
required
string (R2 Path)

Path to stored document in R2

File Extension (string) or File Extension (null) (File Extension)

File extension without dot (e.g., 'pdf')

FileHandlingTier (string) or null

Processing tier for this file type

Drawing Comparison Id (string) or Drawing Comparison Id (null) (Drawing Comparison Id)

ID of the drawing comparison record, if this document was compared to a previous version

Virtual Document Id (string) or Virtual Document Id (null) (Virtual Document Id)

Reference to the source virtual document if auto-generated from export

Virtual Document Version (integer) or Virtual Document Version (null) (Virtual Document Version)

Version number of the virtual document if auto-generated from export

auto_generated
boolean (Auto Generated)
Default: false

Flag indicating this document was auto-created from a virtual document export

project_id
required
string (Project Id)

ID of project this document belongs to

Organization Id (string) or Organization Id (null) (Organization Id)

ID of organization that generated the document

processing_status
required
string (DocumentProcessingStatus)
Enum: "PENDING" "QUEUED" "PROCESSING" "PROCESSED" "FAILED" "DUPLICATE" "PENDING_PROCESSING" "UPLOADED" "ACCEPTED"

Status of document processing

required
object (AssigneeUser)

User who uploaded the document

Responses

Request samples

Content type
application/json
{
  • "document_id": "string",
  • "title": "string",
  • "document_reference": "string",
  • "description": "string",
  • "status": "draft",
  • "revision": "string",
  • "category": "string",
  • "document_type": "brochure",
  • "content": "string",
  • "summary": "string",
  • "purpose": "string",
  • "keywords": [ ],
  • "file_path": "string",
  • "file_size": 0,
  • "mime_type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version_history": [
    ],
  • "thumbnail_image_path": "string",
  • "full_image_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "filename": "string",
  • "r2_path": "string",
  • "file_extension": "string",
  • "file_handling_tier": "RECORD_ONLY",
  • "drawing_comparison_id": "string",
  • "virtual_document_id": "string",
  • "virtual_document_version": 0,
  • "auto_generated": false,
  • "project_id": "string",
  • "organization_id": "string",
  • "processing_status": "PENDING",
  • "uploaded_by": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "filename": "string",
  • "processing_status": "PENDING",
  • "status": "draft",
  • "r2_path": "string",
  • "chunks_count": 0,
  • "full_image_path": "string",
  • "thumbnail_image_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "metadata": {
    },
  • "latest_version": "string",
  • "is_latest": true,
  • "is_deleted": false,
  • "revision": "string",
  • "purpose": "string",
  • "keywords": [ ],
  • "uploaded_by": {
    },
  • "title": "string",
  • "project_id": "string",
  • "organization_id": "string",
  • "document_reference": "string",
  • "description": "string",
  • "category": "string",
  • "document_type": "brochure",
  • "content": "string",
  • "summary": "string",
  • "file_path": "string",
  • "file_size": 0,
  • "mime_type": "string",
  • "drawing_comparison_id": "string"
}

Get Documents

Get all documents with optional filtering and pagination.

Args:

project_id: Project ID filter
organization_id: Optional organization ID filter
document_type: Filter by document type (comma-separated for multiple)
page: Page number (1-based)
size: Number of items per page
created_at_start: Optional inclusive lower bound for created_at
created_at_end: Optional inclusive upper bound for created_at
sort_by: Field to sort by
sort_order: Sort order (asc/desc)
processing_status: Optional processing status filter
exclude_processing_status: Exclude processing statuses (comma-separated for multiple)
is_deleted: Filter by deletion status (default False)
include_images: Include images in the response
image_expiration: Image expiration time in seconds
db: MongoDB client instance

Returns:

Paginated response containing documents and pagination metadata

Raises:

HTTPException: If database operation fails
Authorizations:
HTTPBearer
query Parameters
project_id
required
string (Project Id)

Project ID

Organization Id (string) or Organization Id (null) (Organization Id)

Organization ID

Document Type (string) or Document Type (null) (Document Type)

Filter by document type (comma-separated for multiple, e.g., 'DRAWING,SCHEDULE').

page
integer (Page) >= 1
Default: 1

Page number

size
integer (Size) [ 1 .. 100 ]
Default: 10

Number of items per page

Created At Start (string) or Created At Start (null) (Created At Start)

Return documents created on or after this datetime

Created At End (string) or Created At End (null) (Created At End)

Return documents created on or before this datetime

Sort By (string) or Sort By (null) (Sort By)
Sort Order (string) or Sort Order (null) (Sort Order)
Processing Status (string) or Processing Status (null) (Processing Status)

Processing status filter (comma-separated for multiple, e.g., 'completed,failed')

Exclude Processing Status (string) or Exclude Processing Status (null) (Exclude Processing Status)

Exclude processing statuses (comma-separated for multiple, e.g., 'queued,processing')

is_deleted
boolean (Is Deleted)
Default: false

Filter by deletion status

include_images
boolean (Include Images)
Default: true

Include images in the response

image_expiration
integer (Image Expiration)
Default: 3600

Image expiration time in seconds

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Search Documents

Search documents with comprehensive filtering and text search.

Args:

query: Text search query (searches in title, description, and document_reference)
project_id: Filter by project ID
organization_id: Filter by organization ID
document_type: Filter by document type
status: Filter by document status
category: Filter by document category
uploaded_by: Filter by user who uploaded the document
start_date: Filter by upload date range start
end_date: Filter by upload date range end
sort_by: Field to sort by (default: uploaded_at)
sort_order: Sort order (asc or desc, default: desc)
include_content: Whether to include document content in search (when available)
skip: Number of records to skip
limit: Maximum number of records to return
db: MongoDB client instance

Returns:

List of documents matching the search criteria

Raises:

HTTPException: If database operation fails
Authorizations:
HTTPBearer
query Parameters
Query (string) or Query (null) (Query)
Project Id (string) or Project Id (null) (Project Id)
Organization Id (string) or Organization Id (null) (Organization Id)
Document Type (string) or Document Type (null) (Document Type)
Status (string) or Status (null) (Status)
Category (string) or Category (null) (Category)
Uploaded By (string) or Uploaded By (null) (Uploaded By)
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
Sort By (string) or Sort By (null) (Sort By)
Default: "uploaded_at"
Sort Order (string) or Sort Order (null) (Sort Order)
Default: "desc"
include_content
boolean (Include Content)
Default: false
skip
integer (Skip) >= 0
Default: 0
limit
integer (Limit) [ 1 .. 100 ]
Default: 10

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Documents Batch

Get multiple documents by their IDs in a single request.

Args:

ids: Comma-separated list of document IDs to fetch
db: MongoDB client instance

Returns:

List of documents matching the provided IDs
Authorizations:
HTTPBearer
query Parameters
ids
required
string (Ids)

Comma-separated document IDs

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Document

Get a specific document.

Args:

document_id: ID of document to retrieve
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Document

Raises:

HTTPException: If document not found
Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
{
  • "document_id": "string",
  • "title": "string",
  • "document_reference": "string",
  • "description": "string",
  • "status": "draft",
  • "revision": "string",
  • "category": "string",
  • "document_type": "brochure",
  • "content": "string",
  • "summary": "string",
  • "purpose": "string",
  • "keywords": [ ],
  • "file_path": "string",
  • "file_size": 0,
  • "mime_type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version_history": [
    ],
  • "thumbnail_image_path": "string",
  • "full_image_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "filename": "string",
  • "r2_path": "string",
  • "file_extension": "string",
  • "file_handling_tier": "RECORD_ONLY",
  • "drawing_comparison_id": "string",
  • "virtual_document_id": "string",
  • "virtual_document_version": 0,
  • "auto_generated": false,
  • "_id": "string",
  • "project_id": "string",
  • "organization_id": "string",
  • "uploaded_at": "2019-08-24T14:15:22Z",
  • "last_modified": "2019-08-24T14:15:22Z",
  • "task_ids": [
    ],
  • "related_queries": [
    ]
}

Update Document

Update a document.

Args:

document_id: ID of document to update
document_update: Document update data
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Updated document

Raises:

HTTPException: If document not found or update fails
Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
Request Body schema: application/json
required
Title (string) or Title (null) (Title)
Document Reference (string) or Document Reference (null) (Document Reference)
Description (string) or Description (null) (Description)
Status (string) or Status (null) (Status)
Revision (string) or Revision (null) (Revision)
Category (string) or Category (null) (Category)
DocumentType (string) or null
Content (string) or Content (null) (Content)
Summary (string) or Summary (null) (Summary)
Purpose (string) or Purpose (null) (Purpose)
Array of Keywords (strings) or Keywords (null) (Keywords)
DocumentProcessingStatus (string) or null

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "document_reference": "string",
  • "description": "string",
  • "status": "string",
  • "revision": "string",
  • "category": "string",
  • "document_type": "brochure",
  • "content": "string",
  • "summary": "string",
  • "purpose": "string",
  • "keywords": [
    ],
  • "processing_status": "PENDING"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "filename": "string",
  • "processing_status": "PENDING",
  • "status": "draft",
  • "r2_path": "string",
  • "chunks_count": 0,
  • "full_image_path": "string",
  • "thumbnail_image_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "metadata": {
    },
  • "latest_version": "string",
  • "is_latest": true,
  • "is_deleted": false,
  • "revision": "string",
  • "purpose": "string",
  • "keywords": [ ],
  • "uploaded_by": {
    }
}

Delete Document

Delete a document.

Args:

document_id: ID of document to delete
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Success message

Raises:

HTTPException: If document not found or delete fails
Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Generate Download Link

Generate a temporary download link for a document.

Args:

document_id: ID of document to generate link for
db: MongoDB client instance

Returns:

Dictionary containing download link and expiration time

Raises:

HTTPException: If document not found or link generation fails
Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Generate Batch Download Links

Generate temporary download links for multiple documents.

Args:

request: Batch download request containing document IDs and expiration time
db: MongoDB client instance

Returns:

BatchDownloadResponse containing download URLs and expiration time

Raises:

HTTPException: If any document is not found or link generation fails
Authorizations:
HTTPBearer
Request Body schema: application/json
required
document_ids
required
Array of strings (Document Ids)

List of document IDs to download

expiration
integer (Expiration) [ 300 .. 86400 ]
Default: 3600

URL expiration time in seconds (5 minutes to 24 hours)

Responses

Request samples

Content type
application/json
{
  • "document_ids": [
    ],
  • "expiration": 3600
}

Response samples

Content type
application/json
{
  • "downloads": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z"
}

Update Document Content

Update document content.

Args:

document_id: ID of document to update
content: New document content
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Updated document

Raises:

HTTPException: If document not found or update fails
Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
query Parameters
content
required
string (Content)

Responses

Response samples

Content type
application/json
{
  • "document_id": "string",
  • "title": "string",
  • "document_reference": "string",
  • "description": "string",
  • "status": "draft",
  • "revision": "string",
  • "category": "string",
  • "document_type": "brochure",
  • "content": "string",
  • "summary": "string",
  • "purpose": "string",
  • "keywords": [ ],
  • "file_path": "string",
  • "file_size": 0,
  • "mime_type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version_history": [
    ],
  • "thumbnail_image_path": "string",
  • "full_image_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "filename": "string",
  • "r2_path": "string",
  • "file_extension": "string",
  • "file_handling_tier": "RECORD_ONLY",
  • "drawing_comparison_id": "string",
  • "virtual_document_id": "string",
  • "virtual_document_version": 0,
  • "auto_generated": false,
  • "_id": "string",
  • "project_id": "string",
  • "organization_id": "string",
  • "uploaded_at": "2019-08-24T14:15:22Z",
  • "last_modified": "2019-08-24T14:15:22Z",
  • "task_ids": [
    ],
  • "related_queries": [
    ]
}

Get Drawing Comparison

Get drawing comparison information by ID.

Args:

drawing_comparison_id: ID of the drawing comparison to retrieve
db: MongoDB client instance

Returns:

DrawingComparisonResponse containing the comparison information

Raises:

HTTPException: If comparison not found or database operation fails
Authorizations:
HTTPBearer
path Parameters
drawing_comparison_id
required
string (Drawing Comparison Id)

Responses

Response samples

Content type
application/json
{
  • "drawing_comparison": {
    }
}

Reprocess Document

Manually trigger document processing/reprocessing for a document.

This endpoint is useful for documents that were never processed or failed processing. It will queue the document for chunking and embedding generation.

Uses atomic find_one_and_update to prevent race conditions - only documents that are not already being processed can be queued.

Args:

document_id: ID of the document to reprocess
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Status message indicating the document was queued for processing

Raises:

HTTPException: If document not found, already processing, or queue fails
Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
{ }

Create Drawing Comparison

Manually trigger a drawing comparison between two existing documents.

This endpoint allows creating a comparison for documents that were not automatically compared during upload (e.g., due to processing order or status issues).

The comparison will:

  1. Fetch both documents and validate they exist
  2. Download their full images from R2 storage
  3. Upload images to MyDrawIt and run the comparison
  4. Store the comparison record and link it to the newer document

Args:

original_document_id: ID of the original (older) document
comparison_document_id: ID of the comparison (newer) document
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Comparison result with the comparison ID

Raises:

HTTPException: If documents not found, missing images, or comparison fails
Authorizations:
HTTPBearer
query Parameters
original_document_id
required
string (Original Document Id)

ID of the original (older) document

comparison_document_id
required
string (Comparison Document Id)

ID of the comparison (newer) document

Responses

Response samples

Content type
application/json
{ }

Delete Drawing Comparison

Delete a drawing comparison and unlink the associated documents.

This endpoint allows removing an incorrect comparison between documents. It will:

  1. Delete the comparison record from drawing_comparisons collection
  2. Remove the drawing_comparison_id from the comparison document
  3. Optionally reset the is_latest flags if documents were incorrectly linked

Args:

comparison_id: ID of the comparison to delete
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Status message confirming deletion

Raises:

HTTPException: If comparison not found or deletion fails
Authorizations:
HTTPBearer
path Parameters
comparison_id
required
string (Comparison Id)

Responses

Response samples

Content type
application/json
{ }

email-templates

email-templates endpoints

List Email Templates

List email templates with optional filtering.

Args:

template_type: Optional template type to filter by
organization_id: Optional organization ID to filter by
active_only: Whether to only return active templates
current_user: Current authenticated user

Returns:

List of email templates
Authorizations:
HTTPBearer
query Parameters
EmailTemplateType (string) or Template Type (null) (Template Type)
Organization Id (string) or Organization Id (null) (Organization Id)
active_only
boolean (Active Only)
Default: true

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Email Template

Create a new email template.

Args:

template: Template to create
current_user: Current authenticated user

Returns:

Created template
Authorizations:
HTTPBearer
Request Body schema: application/json
required
_id
string (Id)
created_at
string <date-time> (Created At)
updated_at
string <date-time> (Updated At)
name
required
string (Name)

Name of the template

description
required
string (Description)

Description of the template

template_type
required
string (EmailTemplateType)
Enum: "notification" "digest" "system" "custom"

Type of template

NotificationType (string) or null

Associated notification type if applicable

subject
required
string (Subject)

Email subject template

body
required
string (Body)

Plain text email body template

html_body
required
string (Html Body)

HTML email body template

variables
Array of strings (Variables)

List of variables used in the template

is_active
boolean (Is Active)
Default: true

Whether the template is active

created_by
required
string (Created By)

ID of the user who created the template

Organization Id (string) or Organization Id (null) (Organization Id)

ID of the organization this template belongs to (if organization-specific)

Responses

Request samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "body": "Hello {{user_name}},\n\nYou have been assigned a new task: {{task_name}}\n\nProject: {{project_name}}\nDue Date: {{due_date}}\nPriority: {{priority}}\n\nClick here to view the task: {{task_url}}",
  • "created_at": "2024-01-01T00:00:00Z",
  • "created_by": "507f1f77bcf86cd799439012",
  • "description": "Email sent when a task is assigned to a user",
  • "html_body": "<h2>New Task Assigned</h2><p>Hello {{user_name}},</p><p>You have been assigned a new task: <strong>{{task_name}}</strong></p><p><strong>Project:</strong> {{project_name}}<br><strong>Due Date:</strong> {{due_date}}<br><strong>Priority:</strong> {{priority}}</p><p><a href='{{task_url}}'>Click here to view the task</a></p>",
  • "is_active": true,
  • "name": "Task Assigned Email",
  • "notification_type": "task_assigned",
  • "subject": "New Task Assigned: {{task_name}}",
  • "template_type": "notification",
  • "updated_at": "2024-01-01T00:00:00Z",
  • "variables": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "body": "Hello {{user_name}},\n\nYou have been assigned a new task: {{task_name}}\n\nProject: {{project_name}}\nDue Date: {{due_date}}\nPriority: {{priority}}\n\nClick here to view the task: {{task_url}}",
  • "created_at": "2024-01-01T00:00:00Z",
  • "created_by": "507f1f77bcf86cd799439012",
  • "description": "Email sent when a task is assigned to a user",
  • "html_body": "<h2>New Task Assigned</h2><p>Hello {{user_name}},</p><p>You have been assigned a new task: <strong>{{task_name}}</strong></p><p><strong>Project:</strong> {{project_name}}<br><strong>Due Date:</strong> {{due_date}}<br><strong>Priority:</strong> {{priority}}</p><p><a href='{{task_url}}'>Click here to view the task</a></p>",
  • "is_active": true,
  • "name": "Task Assigned Email",
  • "notification_type": "task_assigned",
  • "subject": "New Task Assigned: {{task_name}}",
  • "template_type": "notification",
  • "updated_at": "2024-01-01T00:00:00Z",
  • "variables": [
    ]
}

Get Email Template

Get an email template by ID.

Args:

template_id: ID of the template to retrieve
current_user: Current authenticated user

Returns:

Email template

Raises:

HTTPException: If template not found
Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "body": "Hello {{user_name}},\n\nYou have been assigned a new task: {{task_name}}\n\nProject: {{project_name}}\nDue Date: {{due_date}}\nPriority: {{priority}}\n\nClick here to view the task: {{task_url}}",
  • "created_at": "2024-01-01T00:00:00Z",
  • "created_by": "507f1f77bcf86cd799439012",
  • "description": "Email sent when a task is assigned to a user",
  • "html_body": "<h2>New Task Assigned</h2><p>Hello {{user_name}},</p><p>You have been assigned a new task: <strong>{{task_name}}</strong></p><p><strong>Project:</strong> {{project_name}}<br><strong>Due Date:</strong> {{due_date}}<br><strong>Priority:</strong> {{priority}}</p><p><a href='{{task_url}}'>Click here to view the task</a></p>",
  • "is_active": true,
  • "name": "Task Assigned Email",
  • "notification_type": "task_assigned",
  • "subject": "New Task Assigned: {{task_name}}",
  • "template_type": "notification",
  • "updated_at": "2024-01-01T00:00:00Z",
  • "variables": [
    ]
}

Update Email Template

Update an email template.

Args:

template_id: ID of the template to update
template: Updated template data
current_user: Current authenticated user

Returns:

Updated template

Raises:

HTTPException: If template not found
Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)
Request Body schema: application/json
required
_id
string (Id)
created_at
string <date-time> (Created At)
updated_at
string <date-time> (Updated At)
name
required
string (Name)

Name of the template

description
required
string (Description)

Description of the template

template_type
required
string (EmailTemplateType)
Enum: "notification" "digest" "system" "custom"

Type of template

NotificationType (string) or null

Associated notification type if applicable

subject
required
string (Subject)

Email subject template

body
required
string (Body)

Plain text email body template

html_body
required
string (Html Body)

HTML email body template

variables
Array of strings (Variables)

List of variables used in the template

is_active
boolean (Is Active)
Default: true

Whether the template is active

created_by
required
string (Created By)

ID of the user who created the template

Organization Id (string) or Organization Id (null) (Organization Id)

ID of the organization this template belongs to (if organization-specific)

Responses

Request samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "body": "Hello {{user_name}},\n\nYou have been assigned a new task: {{task_name}}\n\nProject: {{project_name}}\nDue Date: {{due_date}}\nPriority: {{priority}}\n\nClick here to view the task: {{task_url}}",
  • "created_at": "2024-01-01T00:00:00Z",
  • "created_by": "507f1f77bcf86cd799439012",
  • "description": "Email sent when a task is assigned to a user",
  • "html_body": "<h2>New Task Assigned</h2><p>Hello {{user_name}},</p><p>You have been assigned a new task: <strong>{{task_name}}</strong></p><p><strong>Project:</strong> {{project_name}}<br><strong>Due Date:</strong> {{due_date}}<br><strong>Priority:</strong> {{priority}}</p><p><a href='{{task_url}}'>Click here to view the task</a></p>",
  • "is_active": true,
  • "name": "Task Assigned Email",
  • "notification_type": "task_assigned",
  • "subject": "New Task Assigned: {{task_name}}",
  • "template_type": "notification",
  • "updated_at": "2024-01-01T00:00:00Z",
  • "variables": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "body": "Hello {{user_name}},\n\nYou have been assigned a new task: {{task_name}}\n\nProject: {{project_name}}\nDue Date: {{due_date}}\nPriority: {{priority}}\n\nClick here to view the task: {{task_url}}",
  • "created_at": "2024-01-01T00:00:00Z",
  • "created_by": "507f1f77bcf86cd799439012",
  • "description": "Email sent when a task is assigned to a user",
  • "html_body": "<h2>New Task Assigned</h2><p>Hello {{user_name}},</p><p>You have been assigned a new task: <strong>{{task_name}}</strong></p><p><strong>Project:</strong> {{project_name}}<br><strong>Due Date:</strong> {{due_date}}<br><strong>Priority:</strong> {{priority}}</p><p><a href='{{task_url}}'>Click here to view the task</a></p>",
  • "is_active": true,
  • "name": "Task Assigned Email",
  • "notification_type": "task_assigned",
  • "subject": "New Task Assigned: {{task_name}}",
  • "template_type": "notification",
  • "updated_at": "2024-01-01T00:00:00Z",
  • "variables": [
    ]
}

Delete Email Template

Delete an email template.

Args:

template_id: ID of the template to delete
current_user: Current authenticated user

Raises:

HTTPException: If template not found
Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

List Email Activities

List email activities with optional filtering.

Args:

recipient_id: Optional recipient ID to filter by
template_id: Optional template ID to filter by
notification_id: Optional notification ID to filter by
project_id: Optional project ID to filter by
limit: Maximum number of activities to return
skip: Number of activities to skip (for pagination)
current_user: Current authenticated user

Returns:

List of email activities
Authorizations:
HTTPBearer
query Parameters
Recipient Id (string) or Recipient Id (null) (Recipient Id)
Template Id (string) or Template Id (null) (Template Id)
Notification Id (string) or Notification Id (null) (Notification Id)
Project Id (string) or Project Id (null) (Project Id)
limit
integer (Limit) [ 1 .. 100 ]
Default: 50
skip
integer (Skip) >= 0
Default: 0

Responses

Response samples

Content type
application/json
[
  • {
    }
]

external-systems

external-systems endpoints

Create External System

Create a new external system integration with encrypted credentials.

The credentials provided in the request will be encrypted before storage. They are stored in a separate collection for security.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
system_id
required
string (System Id)

Unique identifier for the system

system_name
required
string (System Name)

Human-readable name

system_type
required
string (ExternalSystemType)
Enum: "rest_api" "soap_api" "graphql" "webhook" "database" "custom"

Types of external systems that can be integrated.

Description (string) or Description (null) (Description)
base_url
required
string (Base Url)

Base URL for API calls

authentication_type
string (AuthenticationType)
Default: "none"
Enum: "none" "api_key" "bearer_token" "basic_auth" "oauth2" "custom_header"

Authentication methods for external systems.

timeout
integer (Timeout)
Default: 30

Request timeout in seconds

retry_attempts
integer (Retry Attempts)
Default: 3

Number of retry attempts on failure

Rate Limit Per Minute (integer) or Rate Limit Per Minute (null) (Rate Limit Per Minute)

Maximum requests per minute (None = unlimited)

object (Custom Headers)

Static headers to include in all requests (non-sensitive only)

organization_id
required
string (Organization Id)

Organization that owns this system configuration

created_by_user_id
required
string (Created By User Id)
is_active
boolean (Is Active)
Default: true
is_shared
boolean (Is Shared)
Default: false

If true, can be used across all templates in organization

allowed_template_ids
Array of strings (Allowed Template Ids)

Template IDs allowed to use this system (empty = all if shared)

object (Metadata)

Additional system-specific metadata

Last Tested At (string) or Last Tested At (null) (Last Tested At)
Last Test Status (string) or Last Test Status (null) (Last Test Status)
status
string (ExternalSystemStatus)
Default: "testing"
Enum: "active" "inactive" "error" "testing"

Status of external system integration.

Credentials (object) or Credentials (null) (Credentials)

Plain text credentials to be encrypted

Responses

Request samples

Content type
application/json
{
  • "system_id": "string",
  • "system_name": "string",
  • "system_type": "rest_api",
  • "description": "string",
  • "base_url": "string",
  • "authentication_type": "none",
  • "timeout": 30,
  • "retry_attempts": 3,
  • "rate_limit_per_minute": 0,
  • "custom_headers": {
    },
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "is_active": true,
  • "is_shared": false,
  • "allowed_template_ids": [
    ],
  • "metadata": { },
  • "last_tested_at": "2019-08-24T14:15:22Z",
  • "last_test_status": "string",
  • "status": "active",
  • "credentials": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "system_id": "string",
  • "system_name": "string",
  • "system_type": "rest_api",
  • "description": "string",
  • "base_url": "string",
  • "authentication_type": "none",
  • "timeout": 30,
  • "retry_attempts": 3,
  • "rate_limit_per_minute": 0,
  • "custom_headers": {
    },
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "is_active": true,
  • "is_shared": false,
  • "allowed_template_ids": [
    ],
  • "metadata": { },
  • "last_tested_at": "2019-08-24T14:15:22Z",
  • "last_test_status": "string",
  • "status": "active",
  • "has_credentials": false,
  • "credential_fields": [
    ]
}

Create External System

Create a new external system integration with encrypted credentials.

The credentials provided in the request will be encrypted before storage. They are stored in a separate collection for security.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
system_id
required
string (System Id)

Unique identifier for the system

system_name
required
string (System Name)

Human-readable name

system_type
required
string (ExternalSystemType)
Enum: "rest_api" "soap_api" "graphql" "webhook" "database" "custom"

Types of external systems that can be integrated.

Description (string) or Description (null) (Description)
base_url
required
string (Base Url)

Base URL for API calls

authentication_type
string (AuthenticationType)
Default: "none"
Enum: "none" "api_key" "bearer_token" "basic_auth" "oauth2" "custom_header"

Authentication methods for external systems.

timeout
integer (Timeout)
Default: 30

Request timeout in seconds

retry_attempts
integer (Retry Attempts)
Default: 3

Number of retry attempts on failure

Rate Limit Per Minute (integer) or Rate Limit Per Minute (null) (Rate Limit Per Minute)

Maximum requests per minute (None = unlimited)

object (Custom Headers)

Static headers to include in all requests (non-sensitive only)

organization_id
required
string (Organization Id)

Organization that owns this system configuration

created_by_user_id
required
string (Created By User Id)
is_active
boolean (Is Active)
Default: true
is_shared
boolean (Is Shared)
Default: false

If true, can be used across all templates in organization

allowed_template_ids
Array of strings (Allowed Template Ids)

Template IDs allowed to use this system (empty = all if shared)

object (Metadata)

Additional system-specific metadata

Last Tested At (string) or Last Tested At (null) (Last Tested At)
Last Test Status (string) or Last Test Status (null) (Last Test Status)
status
string (ExternalSystemStatus)
Default: "testing"
Enum: "active" "inactive" "error" "testing"

Status of external system integration.

Credentials (object) or Credentials (null) (Credentials)

Plain text credentials to be encrypted

Responses

Request samples

Content type
application/json
{
  • "system_id": "string",
  • "system_name": "string",
  • "system_type": "rest_api",
  • "description": "string",
  • "base_url": "string",
  • "authentication_type": "none",
  • "timeout": 30,
  • "retry_attempts": 3,
  • "rate_limit_per_minute": 0,
  • "custom_headers": {
    },
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "is_active": true,
  • "is_shared": false,
  • "allowed_template_ids": [
    ],
  • "metadata": { },
  • "last_tested_at": "2019-08-24T14:15:22Z",
  • "last_test_status": "string",
  • "status": "active",
  • "credentials": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "system_id": "string",
  • "system_name": "string",
  • "system_type": "rest_api",
  • "description": "string",
  • "base_url": "string",
  • "authentication_type": "none",
  • "timeout": 30,
  • "retry_attempts": 3,
  • "rate_limit_per_minute": 0,
  • "custom_headers": {
    },
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "is_active": true,
  • "is_shared": false,
  • "allowed_template_ids": [
    ],
  • "metadata": { },
  • "last_tested_at": "2019-08-24T14:15:22Z",
  • "last_test_status": "string",
  • "status": "active",
  • "has_credentials": false,
  • "credential_fields": [
    ]
}

List External Systems

List all external systems for an organization.

Credentials are not included in the response for security.

Authorizations:
HTTPBearer
query Parameters
Organization Id (string) or Organization Id (null) (Organization Id)

Organization ID to filter systems (defaults to current user's org)

include_inactive
boolean (Include Inactive)
Default: false

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List External Systems

List all external systems for an organization.

Credentials are not included in the response for security.

Authorizations:
HTTPBearer
query Parameters
Organization Id (string) or Organization Id (null) (Organization Id)

Organization ID to filter systems (defaults to current user's org)

include_inactive
boolean (Include Inactive)
Default: false

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get External System

Get details of a specific external system.

Credentials are not included in the response for security.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
query Parameters
organization_id
required
string (Organization Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "system_id": "string",
  • "system_name": "string",
  • "system_type": "rest_api",
  • "description": "string",
  • "base_url": "string",
  • "authentication_type": "none",
  • "timeout": 30,
  • "retry_attempts": 3,
  • "rate_limit_per_minute": 0,
  • "custom_headers": {
    },
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "is_active": true,
  • "is_shared": false,
  • "allowed_template_ids": [
    ],
  • "metadata": { },
  • "last_tested_at": "2019-08-24T14:15:22Z",
  • "last_test_status": "string",
  • "status": "active",
  • "has_credentials": false,
  • "credential_fields": [
    ]
}

Get External System

Get details of a specific external system.

Credentials are not included in the response for security.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
query Parameters
organization_id
required
string (Organization Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "system_id": "string",
  • "system_name": "string",
  • "system_type": "rest_api",
  • "description": "string",
  • "base_url": "string",
  • "authentication_type": "none",
  • "timeout": 30,
  • "retry_attempts": 3,
  • "rate_limit_per_minute": 0,
  • "custom_headers": {
    },
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "is_active": true,
  • "is_shared": false,
  • "allowed_template_ids": [
    ],
  • "metadata": { },
  • "last_tested_at": "2019-08-24T14:15:22Z",
  • "last_test_status": "string",
  • "status": "active",
  • "has_credentials": false,
  • "credential_fields": [
    ]
}

Update External System

Update an external system configuration.

If credentials are provided, they will be encrypted and stored securely.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
query Parameters
organization_id
required
string (Organization Id)
Request Body schema: application/json
required
System Name (string) or System Name (null) (System Name)
Description (string) or Description (null) (Description)
Base Url (string) or Base Url (null) (Base Url)
AuthenticationType (string) or null
Timeout (integer) or Timeout (null) (Timeout)
Retry Attempts (integer) or Retry Attempts (null) (Retry Attempts)
Rate Limit Per Minute (integer) or Rate Limit Per Minute (null) (Rate Limit Per Minute)
Custom Headers (object) or Custom Headers (null) (Custom Headers)
Is Active (boolean) or Is Active (null) (Is Active)
Is Shared (boolean) or Is Shared (null) (Is Shared)
Array of Allowed Template Ids (strings) or Allowed Template Ids (null) (Allowed Template Ids)
Metadata (object) or Metadata (null) (Metadata)
ExternalSystemStatus (string) or null
Credentials (object) or Credentials (null) (Credentials)

Updated credentials (plain text, will be encrypted)

Responses

Request samples

Content type
application/json
{
  • "system_name": "string",
  • "description": "string",
  • "base_url": "string",
  • "authentication_type": "none",
  • "timeout": 0,
  • "retry_attempts": 0,
  • "rate_limit_per_minute": 0,
  • "custom_headers": {
    },
  • "is_active": true,
  • "is_shared": true,
  • "allowed_template_ids": [
    ],
  • "metadata": { },
  • "status": "active",
  • "credentials": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "system_id": "string",
  • "system_name": "string",
  • "system_type": "rest_api",
  • "description": "string",
  • "base_url": "string",
  • "authentication_type": "none",
  • "timeout": 30,
  • "retry_attempts": 3,
  • "rate_limit_per_minute": 0,
  • "custom_headers": {
    },
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "is_active": true,
  • "is_shared": false,
  • "allowed_template_ids": [
    ],
  • "metadata": { },
  • "last_tested_at": "2019-08-24T14:15:22Z",
  • "last_test_status": "string",
  • "status": "active",
  • "has_credentials": false,
  • "credential_fields": [
    ]
}

Update External System

Update an external system configuration.

If credentials are provided, they will be encrypted and stored securely.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
query Parameters
organization_id
required
string (Organization Id)
Request Body schema: application/json
required
System Name (string) or System Name (null) (System Name)
Description (string) or Description (null) (Description)
Base Url (string) or Base Url (null) (Base Url)
AuthenticationType (string) or null
Timeout (integer) or Timeout (null) (Timeout)
Retry Attempts (integer) or Retry Attempts (null) (Retry Attempts)
Rate Limit Per Minute (integer) or Rate Limit Per Minute (null) (Rate Limit Per Minute)
Custom Headers (object) or Custom Headers (null) (Custom Headers)
Is Active (boolean) or Is Active (null) (Is Active)
Is Shared (boolean) or Is Shared (null) (Is Shared)
Array of Allowed Template Ids (strings) or Allowed Template Ids (null) (Allowed Template Ids)
Metadata (object) or Metadata (null) (Metadata)
ExternalSystemStatus (string) or null
Credentials (object) or Credentials (null) (Credentials)

Updated credentials (plain text, will be encrypted)

Responses

Request samples

Content type
application/json
{
  • "system_name": "string",
  • "description": "string",
  • "base_url": "string",
  • "authentication_type": "none",
  • "timeout": 0,
  • "retry_attempts": 0,
  • "rate_limit_per_minute": 0,
  • "custom_headers": {
    },
  • "is_active": true,
  • "is_shared": true,
  • "allowed_template_ids": [
    ],
  • "metadata": { },
  • "status": "active",
  • "credentials": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "system_id": "string",
  • "system_name": "string",
  • "system_type": "rest_api",
  • "description": "string",
  • "base_url": "string",
  • "authentication_type": "none",
  • "timeout": 30,
  • "retry_attempts": 3,
  • "rate_limit_per_minute": 0,
  • "custom_headers": {
    },
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "is_active": true,
  • "is_shared": false,
  • "allowed_template_ids": [
    ],
  • "metadata": { },
  • "last_tested_at": "2019-08-24T14:15:22Z",
  • "last_test_status": "string",
  • "status": "active",
  • "has_credentials": false,
  • "credential_fields": [
    ]
}

Delete External System

Delete an external system and its credentials.

This is a hard delete that removes both the system configuration and its encrypted credentials.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
query Parameters
organization_id
required
string (Organization Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete External System

Delete an external system and its credentials.

This is a hard delete that removes both the system configuration and its encrypted credentials.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
query Parameters
organization_id
required
string (Organization Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Test External System

Test connection to an external system.

This makes a real API call to verify the configuration and credentials work.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
query Parameters
organization_id
required
string (Organization Id)
Request Body schema: application/json
required
Test Endpoint (string) or Test Endpoint (null) (Test Endpoint)

Optional endpoint to test (default: /health or base URL)

object (Test Params)

Optional parameters for test request

Responses

Request samples

Content type
application/json
{
  • "test_endpoint": "string",
  • "test_params": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "status_code": 0,
  • "response_time_ms": 0,
  • "error_message": "string",
  • "tested_at": "2019-08-24T14:15:22Z"
}

Test External System

Test connection to an external system.

This makes a real API call to verify the configuration and credentials work.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
query Parameters
organization_id
required
string (Organization Id)
Request Body schema: application/json
required
Test Endpoint (string) or Test Endpoint (null) (Test Endpoint)

Optional endpoint to test (default: /health or base URL)

object (Test Params)

Optional parameters for test request

Responses

Request samples

Content type
application/json
{
  • "test_endpoint": "string",
  • "test_params": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "status_code": 0,
  • "response_time_ms": 0,
  • "error_message": "string",
  • "tested_at": "2019-08-24T14:15:22Z"
}

Proxy Geoapify Geocode

Proxy Geoapify geocoding via stored credentials (api_key auth).

Accepts JSON body with text/limit and optional organization_id.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
Request Body schema: application/json
required
text
required
string (Text)
limit
integer (Limit)
Default: 1
Organization Id (string) or Organization Id (null) (Organization Id)

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "limit": 1,
  • "organization_id": "string"
}

Response samples

Content type
application/json
{ }

Proxy Geoapify Geocode

Proxy Geoapify geocoding via stored credentials (api_key auth).

Accepts JSON body with text/limit and optional organization_id.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
Request Body schema: application/json
required
text
required
string (Text)
limit
integer (Limit)
Default: 1
Organization Id (string) or Organization Id (null) (Organization Id)

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "limit": 1,
  • "organization_id": "string"
}

Response samples

Content type
application/json
{ }

forms

Forms & Data Collection

Create, issue, and manage structured forms for data collection.

Features:

  • Create form templates with customizable fields
  • Version control for form schemas
  • Issue forms to internal users or external recipients
  • Multi-section workflow forms with sequential/flexible completion
  • Section-level signatures and approvals
  • Bulk issuance to multiple recipients
  • Public share links for external access
  • File attachments with cloud storage
  • Amendment tracking and audit trails
  • Table view for bulk data analysis

Form Types:

  • assigned: One recipient, one submission (default)
  • open: Multiple submissions allowed from anyone with link
  • anonymous: Anonymous submissions without authentication

Workflow Modes:

  • sequential: Sections must be completed in order
  • flexible: Sections can be completed in any order

Create a form template

Create a new form template for structured data collection.

Templates define the metadata for a form (name, description, category, tags) and can be scoped to the app, organization, or a specific project:

  • App scope (scope: "app"): Template is available app-wide across all organizations. These are system templates managed by platform administrators.
  • Organization scope (scope: "org"): Template is available across all projects within the organization.
  • Project scope (scope: "project"): Template is only available within the specified project. Requires project_id to be set.

After creating a template, you must create at least one version with a schema before the form can be issued to recipients.

Example request:

{
  "scope": "org",
  "name": "Safety Inspection Checklist",
  "description": "Daily safety inspection form for construction sites",
  "category": "Safety",
  "tags": ["safety", "daily", "inspection"]
}
Authorizations:
HTTPBearer
Request Body schema: application/json
required
scope
required
string (FormTemplateScope)
Enum: "app" "org" "project"

Template visibility scope: 'app' for app-wide system templates, 'org' for organization-wide, 'project' for project-specific.

Project Id (string) or Project Id (null) (Project Id)

Project ID. Required when scope is 'project', must be null for 'org' or 'app'.

name
required
string (Name) <= 200 characters

Display name for the template. Should be descriptive and unique within the scope.

Description (string) or Description (null) (Description)

Detailed description of the form's purpose and usage.

(Category (ReportCategory (string) or Category (string))) or Category (null) (Category)

Category for organizing templates. Use standard report categories when possible.

tags
Array of strings (Tags)

Tags for filtering and searching templates. Example: ['safety', 'daily'].

FormSequenceConfig (object) or null

Configuration for auto-generated form reference numbers. When enabled, each issued form gets a unique reference like 'TQ-00001'.

Responses

Request samples

Content type
application/json
{
  • "scope": "app",
  • "project_id": "string",
  • "name": "string",
  • "description": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "sequence_config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "scope": "app",
  • "organization_id": "string",
  • "project_id": "string",
  • "name": "string",
  • "description": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "is_system": true,
  • "created_by_user_id": "string",
  • "is_deleted": true,
  • "latest_version_number": 0,
  • "latest_version_id": "string",
  • "sequence_config": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List form templates

List form templates with optional filtering and pagination.

Returns templates that the current user has access to based on their organization membership and project permissions. App-wide templates are always included in the results.

Filtering options:

  • project_id: Filter to templates for a specific project (includes org and app-scoped)
  • scope: Filter by scope ("app", "org", or "project")
  • category: Filter by category name (exact match)
  • tags: Filter by tags (comma-separated, matches any)
  • include_app_templates: Include app-wide templates (default: true)

Templates are returned in order of most recently updated first.

Authorizations:
HTTPBearer
query Parameters
Project Id (string) or Project Id (null) (Project Id)

Filter by project ID. Returns project-scoped templates plus org and app-scoped templates.

FormTemplateScope (string) or Scope (null) (Scope)

Filter by template scope: 'app' for app-wide, 'org' for organization-wide, 'project' for project-specific.

include_app_templates
boolean (Include App Templates)
Default: true

Include app-wide system templates in results (default: true).

Category (string) or Category (null) (Category)

Filter by category name (exact match, case-sensitive).

Tags (string) or Tags (null) (Tags)

Comma-separated list of tags. Returns templates matching any of the specified tags.

page
integer (Page) >= 1
Default: 1

Page number (1-based).

size
integer (Size) [ 1 .. 100 ]
Default: 20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Get a form template

Retrieve a specific form template by its ID.

Returns the complete template including metadata, latest version information, and audit fields (created_at, updated_at, created_by).

Use latest_version_id to fetch the current active version's schema.

Error responses:

  • 404: Template not found or user doesn't have access
Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "scope": "app",
  • "organization_id": "string",
  • "project_id": "string",
  • "name": "string",
  • "description": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "is_system": true,
  • "created_by_user_id": "string",
  • "is_deleted": true,
  • "latest_version_number": 0,
  • "latest_version_id": "string",
  • "sequence_config": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a form template

Update a form template's metadata.

Only the following fields can be updated (non-versioned):

  • name: Template display name
  • description: Template description
  • category: Category for organization
  • tags: Tags for filtering
  • archived: Archive/unarchive the template

Note: To change the form schema (fields, validation), create a new version using the POST /templates/{template_id}/versions endpoint.

Example request:

{
  "name": "Updated Safety Checklist",
  "tags": ["safety", "updated", "v2"]
}
Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

New display name for the template.

Description (string) or Description (null) (Description)

New description for the template.

(Category (ReportCategory (string) or Category (string))) or Category (null) (Category)

New category for the template.

Array of Tags (strings) or Tags (null) (Tags)

New tags list. Replaces existing tags entirely.

FormSequenceConfig (object) or null

Updated sequence configuration for form references.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "sequence_config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "scope": "app",
  • "organization_id": "string",
  • "project_id": "string",
  • "name": "string",
  • "description": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "is_system": true,
  • "created_by_user_id": "string",
  • "is_deleted": true,
  • "latest_version_number": 0,
  • "latest_version_id": "string",
  • "sequence_config": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get available template variables

Get the list of available template variables that can be used in form field default values.

Template variables use Jinja2 syntax (e.g., {{ user.name }}) and are rendered when a form instance is created (issued). This enables dynamic default values such as:

  • User variables: Issuer's name, email, first/last name
  • Organization variables: Organization name
  • Project variables: Project name and reference (requires project context)
  • Form variables: Auto-generated reference number and sequence (requires sequence config)
  • Date variables: Today's date, current datetime

Example usage in field default_value_template:

{{ user.name }}           → "John Smith"
{{ form.reference }}      → "TQ-00042"
{{ today }}               → "2026-01-10"
{{ today_formatted }}     → "10 January 2026"

Query parameters can filter variables based on available context:

  • has_project=true: Include project-specific variables
  • has_sequence=true: Include form reference/sequence variables
Authorizations:
HTTPBearer
query Parameters
has_project
boolean (Has Project)
Default: true

Include project-related variables (requires project context when rendering)

has_sequence
boolean (Has Sequence)
Default: true

Include form reference variables (requires sequence config on template)

Responses

Response samples

Content type
application/json
{
  • "variables": [
    ]
}

Preview next form reference

Preview what the next auto-generated form reference will look like for a template.

Returns the current sequence value and a preview of the next reference that will be generated when a new form instance is issued.

Note: This endpoint requires the template to have sequence_config.enabled=true.

Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)
query Parameters
Project Id (string) or Project Id (null) (Project Id)

Project ID for project-scoped sequences

Responses

Response samples

Content type
application/json
{ }

Create a form version

Create a new immutable version of a form template's schema.

Form versions define the actual form structure including:

  • schema: Field definitions with types, labels, and validation rules
  • ui_schema: Layout and display configuration
  • workflow_config: Optional multi-section workflow settings
  • on_submit_task: Optional agent task to trigger on submission

Version numbering: Versions are automatically numbered sequentially (1, 2, 3...). Once created, versions cannot be modified - create a new version for changes.

Supported field types:

  • text, textarea, email, phone, url
  • number, currency
  • date, datetime, time
  • select, multi_select, radio, checkbox
  • file, signature
  • section (for grouping fields)

Example request:

{
  "schema": {
    "fields": [
      {
        "id": "inspector_name",
        "type": "text",
        "label": "Inspector Name",
        "constraints": {"required": true, "maxLength": 100}
      },
      {
        "id": "inspection_date",
        "type": "date",
        "label": "Inspection Date",
        "constraints": {"required": true}
      }
    ]
  },
  "ui_schema": {
    "layout": "vertical",
    "columns": 1
  }
}
Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)
Request Body schema: application/json
required
required
object (FormSchema-Input)

Complete form schema definition.

FormUISchema (object) or null
Array of Summary Config (strings) or Summary Config (null) (Summary Config)
object (Default Prefill Values)
default_locked_field_ids
Array of strings (Default Locked Field Ids)
default_hidden_field_ids
Array of strings (Default Hidden Field Ids)
FormWorkflowConfig (object) or null
Array of objects (On Submit Tasks)

Responses

Request samples

Content type
application/json
{
  • "schema": {
    },
  • "ui_schema": {
    },
  • "summary_config": [
    ],
  • "default_prefill_values": { },
  • "default_locked_field_ids": [
    ],
  • "default_hidden_field_ids": [
    ],
  • "workflow_config": {
    },
  • "on_submit_tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "template_id": "string",
  • "version_number": 0,
  • "schema": {
    },
  • "ui_schema": {
    },
  • "summary_config": [
    ],
  • "default_prefill_values": { },
  • "default_locked_field_ids": [
    ],
  • "default_hidden_field_ids": [
    ],
  • "workflow_config": {
    },
  • "on_submit_tasks": [
    ],
  • "created_by_user_id": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

List form versions

List all versions of a form template with pagination.

Versions are returned in descending order by version number (newest first). Each version contains the complete schema and configuration at that point in time.

Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)
query Parameters
page
integer (Page) >= 1
Default: 1

Page number (1-based).

size
integer (Size) [ 1 .. 100 ]
Default: 20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Get the latest form version

Retrieve the latest (most recent) version of a form template.

Returns the complete version including schema, UI configuration, workflow settings, and any on-submit task triggers.

This is a convenience endpoint that combines:

  1. Fetching the template to get latest_version_id
  2. Fetching that version's full details

Use this when you need the current active schema for a template.

Error responses:

  • 404: Template not found, user doesn't have access, or no versions exist
Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "template_id": "string",
  • "version_number": 0,
  • "schema": {
    },
  • "ui_schema": {
    },
  • "summary_config": [
    ],
  • "default_prefill_values": { },
  • "default_locked_field_ids": [
    ],
  • "default_hidden_field_ids": [
    ],
  • "workflow_config": {
    },
  • "on_submit_tasks": [
    ],
  • "created_by_user_id": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Get a form version

Retrieve a specific form version by its ID.

Returns the complete version including schema, UI configuration, workflow settings, and any on-submit task triggers.

Use this endpoint to get the form structure for rendering a form instance.

Authorizations:
HTTPBearer
path Parameters
version_id
required
string (Version Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "template_id": "string",
  • "version_number": 0,
  • "schema": {
    },
  • "ui_schema": {
    },
  • "summary_config": [
    ],
  • "default_prefill_values": { },
  • "default_locked_field_ids": [
    ],
  • "default_hidden_field_ids": [
    ],
  • "workflow_config": {
    },
  • "on_submit_tasks": [
    ],
  • "created_by_user_id": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Issue a form instance

Issue a new form instance to a recipient.

Form instances are issued copies of a form that can be filled out and submitted. The instance uses the template's latest version at the time of issuance.

Instance types:

  • assigned (default): One recipient, one submission. The form is complete after submission.
  • open: Multiple submissions allowed. Anyone with the link can submit.
  • anonymous: Anonymous submissions without authentication tracking.

Recipients:

  • Internal users: Set issued_to_user_id to a user's ID
  • External users: Set issued_to_external with name and email

Public links: Set create_public_link: true to generate a shareable URL that doesn't require authentication. Required for external recipients.

Example request for internal user:

{
  "template_id": "507f1f77bcf86cd799439011",
  "issued_to_user_id": "507f1f77bcf86cd799439012",
  "title": "Safety Inspection - Building A",
  "instructions": "Please complete by end of day",
  "due_date": "2024-12-31T23:59:59Z"
}

Example request for external user:

{
  "template_id": "507f1f77bcf86cd799439011",
  "issued_to_external": {
    "name": "John Contractor",
    "email": "john@contractor.com",
    "company": "ABC Construction"
  },
  "create_public_link": true,
  "instance_type": "assigned"
}
Authorizations:
HTTPBearer
Request Body schema: application/json
required
template_id
required
string (Template Id)

ID of the form template to issue. The latest version will be used unless version_id is specified.

Version Id (string) or Version Id (null) (Version Id)

Specific version ID to use. If not provided, the template's latest version is used.

Project Id (string) or Project Id (null) (Project Id)

Project to associate this instance with. Optional for org-scoped templates.

Issued To User Id (string) or Issued To User Id (null) (Issued To User Id)

Internal user ID to issue the form to. Mutually exclusive with issued_to_external.

IssuedToExternal (object) or null

External recipient info. Requires create_public_link=true for access.

instance_type
string (FormInstanceType)
Default: "assigned"
Enum: "assigned" "open" "anonymous"

Instance type determining submission behavior. Default: 'assigned' (one submission).

Expires In Days (integer) or Expires In Days (null) (Expires In Days)

Number of days until the form expires. 0 or null means no expiration.

create_public_link
boolean (Create Public Link)
Default: false

Generate a public shareable URL. Required for external recipients.

generate_qr_code
boolean (Generate Qr Code)
Default: false

Generate a QR code for this form instance

Title (string) or Title (null) (Title)

Custom title for this instance. Overrides the template name in the recipient's view.

Instructions (string) or Instructions (null) (Instructions)

Instructions to display to the recipient when they open the form.

Array of Section Assignments (objects) or Section Assignments (null) (Section Assignments)

Initial section assignments for workflow forms. Each section can have different assignees.

Prefill Values (object) or Prefill Values (null) (Prefill Values)

Values to prefill in the form. Keys are field IDs from the schema.

Array of Locked Field Ids (strings) or Locked Field Ids (null) (Locked Field Ids)

Field IDs that are visible but read-only. Useful with prefill_values for context fields.

Array of Hidden Field Ids (strings) or Hidden Field Ids (null) (Hidden Field Ids)

Field IDs to hide from the recipient. Hidden fields can still have prefilled values.

Responses

Request samples

Content type
application/json
{
  • "template_id": "string",
  • "version_id": "string",
  • "project_id": "string",
  • "issued_to_user_id": "string",
  • "issued_to_external": {
    },
  • "instance_type": "assigned",
  • "expires_in_days": 365,
  • "create_public_link": false,
  • "generate_qr_code": false,
  • "title": "string",
  • "instructions": "string",
  • "section_assignments": [
    ],
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "template_id": "string",
  • "version_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "issued_by_user_id": "string",
  • "issued_to_user_id": "string",
  • "issued_to_external": {
    },
  • "instance_type": "assigned",
  • "status": "issued",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "public_share_id": "string",
  • "public_share_url": "string",
  • "qr_code_url": "string",
  • "title": "string",
  • "instructions": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "section_assignments": [
    ],
  • "current_section_order": 0,
  • "workflow_status": "pending",
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List form instances

List form instances with filtering and pagination.

Returns instances that the current user has access to. Results are ordered by creation date (newest first).

Status values:

  • issued: Form has been issued but not yet submitted
  • in_progress: Form is partially complete (workflow forms)
  • completed: Form has been submitted/completed
  • expired: Form passed its due date without completion
  • cancelled: Form was cancelled by the issuer
Authorizations:
HTTPBearer
query Parameters
Project Id (string) or Project Id (null) (Project Id)

Filter by project ID.

Template Id (string) or Template Id (null) (Template Id)

Filter by template ID.

FormInstanceStatus (string) or Status (null) (Status)

Filter by instance status: issued, in_progress, completed, expired, cancelled.

Issued By User Id (string) or Issued By User Id (null) (Issued By User Id)

Filter by the user who issued the form.

Issued To User Id (string) or Issued To User Id (null) (Issued To User Id)

Filter by the user the form was issued to (internal users only).

Expires Before (string) or Expires Before (null) (Expires Before)

Filter instances expiring before this date (ISO 8601 format).

Expires After (string) or Expires After (null) (Expires After)

Filter instances expiring after this date (ISO 8601 format).

page
integer (Page) >= 1
Default: 1

Page number (1-based).

size
integer (Size) [ 1 .. 100 ]
Default: 20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Download QR code image

Download the QR code image for a form instance as a PNG file.

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)

Responses

Response samples

Content type
null

Bulk issue form instances

Issue multiple form instances at once to a list of recipients.

This endpoint is optimized for issuing forms to many recipients in a single request. Maximum 500 recipients per request.

Use cases:

  • Onboarding new contractors with required forms
  • Distributing surveys to project team members
  • Sending inspection forms to multiple site supervisors

Each recipient receives their own independent form instance. The response includes lists of successfully created instances and any failures.

Example request:

{
  "template_id": "507f1f77bcf86cd799439011",
  "recipients": [
    {"user_id": "507f1f77bcf86cd799439012"},
    {"external": {"name": "Jane Doe", "email": "jane@example.com"}},
    {"external": {"name": "Bob Smith", "email": "bob@example.com"}}
  ],
  "instance_type": "assigned",
  "create_public_links": true,
  "title": "Weekly Safety Report",
  "due_date": "2024-12-31T23:59:59Z"
}

Response includes:

  • created: List of successfully created instances with public share URLs
  • failed: List of recipients that failed with error details
  • total_requested, total_created, total_failed: Summary counts
Authorizations:
HTTPBearer
Request Body schema: application/json
required
template_id
required
string (Template Id)
Version Id (string) or Version Id (null) (Version Id)
Project Id (string) or Project Id (null) (Project Id)
Array of objects (Recipients) <= 500 items
instance_type
string (FormInstanceType)
Default: "assigned"
Enum: "assigned" "open" "anonymous"

Type of form instance determining submission behavior.

Values: ASSIGNED: Default type. One recipient, one submission allowed. The form is complete after a single submission. OPEN: Multiple submissions allowed. Anyone with the link can submit multiple times. Useful for surveys or feedback forms. ANONYMOUS: Like OPEN, but submissions are not linked to any user identity. Useful for truly anonymous feedback.

Expires In Days (integer) or Expires In Days (null) (Expires In Days)

Days until expiry (0 or null = no expiry)

create_public_links
boolean (Create Public Links)
Default: false
Title (string) or Title (null) (Title)
Instructions (string) or Instructions (null) (Instructions)
Prefill Values (object) or Prefill Values (null) (Prefill Values)

Instance-specific values to prefill into each issued form.

Array of Locked Field Ids (strings) or Locked Field Ids (null) (Locked Field Ids)

Field IDs that are visible but not editable by the completer.

Array of Hidden Field Ids (strings) or Hidden Field Ids (null) (Hidden Field Ids)

Field IDs that should be hidden from the completer.

Responses

Request samples

Content type
application/json
{
  • "template_id": "string",
  • "version_id": "string",
  • "project_id": "string",
  • "recipients": [
    ],
  • "instance_type": "assigned",
  • "expires_in_days": 365,
  • "create_public_links": false,
  • "title": "string",
  • "instructions": "string",
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "created": [
    ],
  • "failed": [
    ],
  • "total_requested": 0,
  • "total_created": 0,
  • "total_failed": 0
}

Get Instance

Get a form instance by ID.

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "template_id": "string",
  • "version_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "issued_by_user_id": "string",
  • "issued_to_user_id": "string",
  • "issued_to_external": {
    },
  • "instance_type": "assigned",
  • "status": "issued",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "public_share_id": "string",
  • "public_share_url": "string",
  • "qr_code_url": "string",
  • "title": "string",
  • "instructions": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "section_assignments": [
    ],
  • "current_section_order": 0,
  • "workflow_status": "pending",
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Cancel Instance

Cancel a form instance.

Only instances with status 'issued' or 'in_progress' can be cancelled.

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "template_id": "string",
  • "version_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "issued_by_user_id": "string",
  • "issued_to_user_id": "string",
  • "issued_to_external": {
    },
  • "instance_type": "assigned",
  • "status": "issued",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "public_share_id": "string",
  • "public_share_url": "string",
  • "qr_code_url": "string",
  • "title": "string",
  • "instructions": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "section_assignments": [
    ],
  • "current_section_order": 0,
  • "workflow_status": "pending",
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Presign Form Attachment Upload

Presign an upload URL for a form attachment.

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)
Request Body schema: application/json
required
instance_id
required
string (Instance Id)
field_id
required
string (Field Id)
filename
required
string (Filename)
content_type
required
string (Content Type)
size_bytes
required
integer (Size Bytes) >= 1

Responses

Request samples

Content type
application/json
{
  • "instance_id": "string",
  • "field_id": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 1
}

Response samples

Content type
application/json
{
  • "attachment_id": "string",
  • "upload_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "r2_key": "string",
  • "required_headers": {
    }
}

Presign Form Attachment Upload V2

Presign an upload URL for a form attachment.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
instance_id
required
string (Instance Id)
field_id
required
string (Field Id)
filename
required
string (Filename)
content_type
required
string (Content Type)
size_bytes
required
integer (Size Bytes) >= 1

Responses

Request samples

Content type
application/json
{
  • "instance_id": "string",
  • "field_id": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 1
}

Response samples

Content type
application/json
{
  • "attachment_id": "string",
  • "upload_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "r2_key": "string",
  • "required_headers": {
    }
}

Confirm Form Attachment Upload

Confirm an attachment upload and (optionally) generate a thumbnail.

Authorizations:
HTTPBearer
path Parameters
attachment_id
required
string (Attachment Id)
Request Body schema: application/json
required
Checksum (string) or Checksum (null) (Checksum)
Any of
string (Checksum)

Responses

Request samples

Content type
application/json
{
  • "checksum": "string"
}

Response samples

Content type
application/json
{
  • "attachment_id": "string",
  • "r2_key": "string",
  • "thumbnail_url": "string",
  • "status": "ready"
}

Get Form Attachment Url

Get presigned download URLs for an attachment.

Authorizations:
HTTPBearer
path Parameters
attachment_id
required
string (Attachment Id)

Responses

Response samples

Content type
application/json
{
  • "download_url": "string",
  • "thumbnail_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Delete Form Attachment

Delete an unused attachment.

Authorizations:
HTTPBearer
path Parameters
attachment_id
required
string (Attachment Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Submit a form

Submit a form instance for the first time.

Creates a new submission record with the provided field values. For assigned instance types, this completes the form. For open instances, additional submissions can be made.

Validation:

  • Field values are validated against the form schema
  • Required fields must be provided
  • Field types are validated (e.g., dates must be valid ISO 8601 strings)

For workflow forms: Use the section completion endpoints instead of this endpoint. This endpoint is for simple (non-workflow) forms.

Example request:

{
  "values": {
    "inspector_name": "John Smith",
    "inspection_date": "2024-01-15",
    "items_checked": ["safety_equipment", "fire_exits"],
    "notes": "All items passed inspection"
  },
  "description": "Weekly safety inspection completed"
}

Error responses:

  • 400: Validation errors in field values
  • 404: Instance not found
  • 409: Instance already has a submission (for assigned type)
Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)
Request Body schema: application/json
required
required
object (Values)

Form field values as a dictionary mapping field IDs to their values. Each key should match a field ID from the form schema. Values should match the expected type for each field (string, number, array for multi-select, etc.).

Description (string) or Description (null) (Description)

Optional description or notes about this submission.

Responses

Request samples

Content type
application/json
{
  • "values": { },
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "instance_id": "string",
  • "template_id": "string",
  • "version_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "issued_by_user_id": "string",
  • "completed_by_user_id": "string",
  • "completed_by_external": {
    },
  • "description": "string",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "latest_revision_number": 0,
  • "latest_revision_id": "string",
  • "values": { },
  • "values_url": "string",
  • "flat_values": { }
}

Amend a submission

Amend an existing form submission by creating a new revision.

The original submission and all previous revisions are preserved for audit purposes. Each amendment increments the revision number.

Audit trail:

  • Previous values are preserved in the revision history
  • The amender's identity and timestamp are recorded
  • An optional note can explain the reason for the amendment

Example request:

{
  "values": {
    "inspector_name": "John Smith",
    "inspection_date": "2024-01-16",
    "notes": "Updated inspection date to correct day"
  },
  "note": "Corrected inspection date from 15th to 16th"
}
Authorizations:
HTTPBearer
path Parameters
submission_id
required
string (Submission Id)
Request Body schema: application/json
required
required
object (Values)

Updated form field values. Must include all fields, not just changed ones.

Note (string) or Note (null) (Note)

Optional note explaining the reason for the amendment.

Responses

Request samples

Content type
application/json
{
  • "values": { },
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "instance_id": "string",
  • "template_id": "string",
  • "version_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "issued_by_user_id": "string",
  • "completed_by_user_id": "string",
  • "completed_by_external": {
    },
  • "description": "string",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "latest_revision_number": 0,
  • "latest_revision_id": "string",
  • "values": { },
  • "values_url": "string",
  • "flat_values": { }
}

List Submissions

List form submissions with filtering.

Authorizations:
HTTPBearer
query Parameters
Project Id (string) or Project Id (null) (Project Id)
Issued By User Id (string) or Issued By User Id (null) (Issued By User Id)
Completed By User Id (string) or Completed By User Id (null) (Completed By User Id)
Submitted From (string) or Submitted From (null) (Submitted From)
Submitted To (string) or Submitted To (null) (Submitted To)
page
integer (Page) >= 1
Default: 1
size
integer (Size) [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

List Submissions Table

List submissions in table format optimized for grid/spreadsheet views.

Returns

  • columns: Field definitions from the template's latest version schema
  • rows: Submissions with flat_values (no blob fetches required)

This endpoint is optimized for viewing 50+ submissions at once.

Authorizations:
HTTPBearer
query Parameters
template_id
required
string (Template Id)
Project Id (string) or Project Id (null) (Project Id)
page
integer (Page) >= 1
Default: 1
size
integer (Size) [ 1 .. 100 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "template_id": "string",
  • "template_name": "string",
  • "columns": [
    ],
  • "rows": [
    ],
  • "total": 0,
  • "page": 0,
  • "size": 0,
  • "has_more": true
}

Get Submission

Get a specific submission with optional presigned URL to latest blob.

Authorizations:
HTTPBearer
path Parameters
submission_id
required
string (Submission Id)
query Parameters
include_blob_url
boolean (Include Blob Url)
Default: true

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "instance_id": "string",
  • "template_id": "string",
  • "version_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "issued_by_user_id": "string",
  • "completed_by_user_id": "string",
  • "completed_by_external": {
    },
  • "description": "string",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "latest_revision_number": 0,
  • "latest_revision_id": "string",
  • "values": { },
  • "values_url": "string",
  • "flat_values": { }
}

List Revisions

List all revisions of a submission (audit timeline).

Authorizations:
HTTPBearer
path Parameters
submission_id
required
string (Submission Id)
query Parameters
page
integer (Page) >= 1
Default: 1
size
integer (Size) [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Get Revision

Get a specific revision with presigned URL.

Authorizations:
HTTPBearer
path Parameters
submission_id
required
string (Submission Id)
revision_number
required
integer (Revision Number)

Responses

Response samples

Content type
application/json
{ }

Get Batch Submission Values

Fetch full values for multiple submissions at once.

Use this when you need the complete form data for selected submissions (e.g., for export, detailed comparison, or editing).

Max 100 submissions per request.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
submission_ids
required
Array of strings (Submission Ids) <= 100 items

Responses

Request samples

Content type
application/json
{
  • "submission_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "submissions": {
    },
  • "not_found": [
    ]
}

Get section progress

Get the progress summary for all sections in a workflow form instance.

Returns an ordered list of sections with their current status, assignees, and completion information. Use this to display a progress overview or determine which sections the current user can complete.

Section statuses:

  • pending: Section has not been started
  • in_progress: Section is available for completion
  • completed: Section has been submitted
  • amended: Section was completed and later amended

Response includes for each section:

  • Section metadata (id, title, order)
  • Current status and assignees
  • Who completed it and when (if applicable)
  • Whether the current user can complete or amend it
Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Complete Section

Complete a section within a workflow form instance.

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)
section_id
required
string (Section Id)
Request Body schema: application/json
required
section_id
required
string (Section Id)

Section to complete

required
object (Values)

Field values for this section

Signature Data (string) or Signature Data (null) (Signature Data)

Base64/SVG signature data if section requires signature

Responses

Request samples

Content type
application/json
{
  • "section_id": "string",
  • "values": { },
  • "signature_data": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "instance_id": "string",
  • "submission_id": "string",
  • "section_id": "string",
  • "section_order": 0,
  • "revision_number": 0,
  • "completed_by_user_id": "string",
  • "completed_by_external": {
    },
  • "signature": {
    },
  • "status": "completed",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "previous_completion_id": "string",
  • "amendment_note": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Amend Section

Amend a previously completed section.

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)
section_id
required
string (Section Id)
Request Body schema: application/json
required
required
object (Values)

Updated field values

Signature Data (string) or Signature Data (null) (Signature Data)

New signature if section requires signature

Amendment Note (string) or Amendment Note (null) (Amendment Note)

Reason for amendment

Responses

Request samples

Content type
application/json
{
  • "values": { },
  • "signature_data": "string",
  • "amendment_note": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "instance_id": "string",
  • "submission_id": "string",
  • "section_id": "string",
  • "section_order": 0,
  • "revision_number": 0,
  • "completed_by_user_id": "string",
  • "completed_by_external": {
    },
  • "signature": {
    },
  • "status": "completed",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "previous_completion_id": "string",
  • "amendment_note": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Assign Section

Assign a section to specific users (for issuer_assigns_next workflow).

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)
section_id
required
string (Section Id)
Request Body schema: application/json
required
Array of User Ids (strings) or User Ids (null) (User Ids)

List of internal user IDs to assign this section to.

Array of External Assignees (objects) or External Assignees (null) (External Assignees)

List of external assignees with name and email.

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ],
  • "external_assignees": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "template_id": "string",
  • "version_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "issued_by_user_id": "string",
  • "issued_to_user_id": "string",
  • "issued_to_external": {
    },
  • "instance_type": "assigned",
  • "status": "issued",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "public_share_id": "string",
  • "public_share_url": "string",
  • "qr_code_url": "string",
  • "title": "string",
  • "instructions": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "section_assignments": [
    ],
  • "current_section_order": 0,
  • "workflow_status": "pending",
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Section Completions

Get all completions (audit trail) for a section.

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)
section_id
required
string (Section Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

meetings

Meeting Management

Manage construction project meetings and minutes.

Features:

  • Schedule and track meetings
  • Record meeting minutes and action items
  • Link meetings to tasks and documents

List Meetings

List meetings for a project with optional filtering.

Args:

project_id: Project ID
status: Filter by meeting status
skip: Number of records to skip
limit: Maximum number of records to return
current_user: Current authenticated user

Returns:

List of meetings matching the criteria

Raises:

HTTPException: If project not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
query Parameters
Status (string) or Status (null) (Status)
skip
integer (Skip) >= 0
Default: 0
limit
integer (Limit) [ 1 .. 100 ]
Default: 50

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Meeting

Create a new meeting for a project.

Args:

project_id: Project ID
meeting_data: Meeting data
current_user: Current authenticated user

Returns:

Created meeting data

Raises:

HTTPException: If project not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
title
required
string (Title)

Title of the meeting

Description (string) or Description (null) (Description)

Meeting description

project_id
required
string (Project Id)

ID of the project this meeting belongs to

status
string (Status)
Default: "scheduled"

Meeting status (scheduled, in_progress, completed, cancelled)

priority
string (Priority)
Default: "medium"

Meeting priority (low, medium, high, urgent)

start_time
required
string <date-time> (Start Time)

Meeting start time

end_time
required
string <date-time> (End Time)

Meeting end time

Location (string) or Location (null) (Location)

Meeting location (physical or virtual)

meeting_type
string (Meeting Type)
Default: "regular"

Type of meeting (regular, kickoff, review, etc.)

tags
Array of strings (Tags)

Meeting tags

attendees
Array of strings (Attendees)

IDs of users attending the meeting

related_document_ids
Array of strings (Related Document Ids)

IDs of documents related to this meeting

related_task_ids
Array of strings (Related Task Ids)

IDs of tasks related to this meeting

related_milestone_ids
Array of strings (Related Milestone Ids)

IDs of milestones related to this meeting

Notes (string) or Notes (null) (Notes)

Meeting notes or agenda

created_by
required
string (Created By)

ID of the user creating the meeting

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "project_id": "string",
  • "status": "scheduled",
  • "priority": "medium",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "location": "string",
  • "meeting_type": "regular",
  • "tags": [
    ],
  • "attendees": [
    ],
  • "related_document_ids": [
    ],
  • "related_task_ids": [
    ],
  • "related_milestone_ids": [
    ],
  • "notes": "string",
  • "created_by": "string"
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "created_at": "2024-01-01T00:00:00",
  • "created_by": "507f1f77bcf86cd799439013",
  • "description": "Weekly review of project progress",
  • "end_time": "2024-01-01T11:00:00",
  • "location": "Conference Room A",
  • "meeting_type": "regular",
  • "priority": "medium",
  • "project_id": "507f1f77bcf86cd799439012",
  • "related_document_ids": [
    ],
  • "start_time": "2024-01-01T10:00:00",
  • "status": "scheduled",
  • "title": "Weekly Project Review",
  • "updated_at": "2024-01-01T00:00:00"
}

Get Meeting

Get meeting by ID.

Args:

meeting_id: Meeting ID
current_user: Current authenticated user

Returns:

Meeting data

Raises:

HTTPException: If meeting not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
meeting_id
required
string (Meeting Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "created_at": "2024-01-01T00:00:00",
  • "created_by": "507f1f77bcf86cd799439013",
  • "description": "Weekly review of project progress",
  • "end_time": "2024-01-01T11:00:00",
  • "location": "Conference Room A",
  • "meeting_type": "regular",
  • "priority": "medium",
  • "project_id": "507f1f77bcf86cd799439012",
  • "related_document_ids": [
    ],
  • "start_time": "2024-01-01T10:00:00",
  • "status": "scheduled",
  • "title": "Weekly Project Review",
  • "updated_at": "2024-01-01T00:00:00"
}

Update Meeting

Update a meeting.

Args:

meeting_id: Meeting ID
updates: Meeting updates
current_user: Current authenticated user

Returns:

Updated meeting data

Raises:

HTTPException: If user not authorized or meeting not found
Authorizations:
HTTPBearer
path Parameters
meeting_id
required
string (Meeting Id)
Request Body schema: application/json
required
Title (string) or Title (null) (Title)
Description (string) or Description (null) (Description)
Status (string) or Status (null) (Status)
Priority (string) or Priority (null) (Priority)
Start Time (string) or Start Time (null) (Start Time)
End Time (string) or End Time (null) (End Time)
Location (string) or Location (null) (Location)
Meeting Type (string) or Meeting Type (null) (Meeting Type)
Array of Tags (strings) or Tags (null) (Tags)
Array of Attendees (strings) or Attendees (null) (Attendees)
Array of Related Document Ids (strings) or Related Document Ids (null) (Related Document Ids)
Array of Related Task Ids (strings) or Related Task Ids (null) (Related Task Ids)
Array of Related Milestone Ids (strings) or Related Milestone Ids (null) (Related Milestone Ids)
Notes (string) or Notes (null) (Notes)
Updated By (string) or Updated By (null) (Updated By)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "status": "string",
  • "priority": "string",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "location": "string",
  • "meeting_type": "string",
  • "tags": [
    ],
  • "attendees": [
    ],
  • "related_document_ids": [
    ],
  • "related_task_ids": [
    ],
  • "related_milestone_ids": [
    ],
  • "notes": "string",
  • "updated_by": "string"
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "created_at": "2024-01-01T00:00:00",
  • "created_by": "507f1f77bcf86cd799439013",
  • "description": "Weekly review of project progress",
  • "end_time": "2024-01-01T11:00:00",
  • "location": "Conference Room A",
  • "meeting_type": "regular",
  • "priority": "medium",
  • "project_id": "507f1f77bcf86cd799439012",
  • "related_document_ids": [
    ],
  • "start_time": "2024-01-01T10:00:00",
  • "status": "scheduled",
  • "title": "Weekly Project Review",
  • "updated_at": "2024-01-01T00:00:00"
}

Delete Meeting

Delete a meeting.

Args:

meeting_id: Meeting ID
current_user: Current authenticated user

Returns:

Success message

Raises:

HTTPException: If user not authorized or meeting not found
Authorizations:
HTTPBearer
path Parameters
meeting_id
required
string (Meeting Id)

Responses

Response samples

Content type
application/json
null

organizations

Organization Management

Manage organization settings and team members.

Features:

  • View and update organization details
  • Manage team member roles and permissions
  • Configure organization-wide settings

List Organizations

List all organizations with optional fuzzy search.

Args:

current_user: Current authenticated user
search: Optional search query for fuzzy matching
threshold: Minimum fuzzy match score (0-100, default: 60)

Returns:

List of organizations with presigned logo URLs, filtered by search if provided
Authorizations:
HTTPBearer
query Parameters
Search (string) or Search (null) (Search)

Search query for fuzzy matching organization names

threshold
integer (Threshold) [ 0 .. 100 ]
Default: 60

Minimum fuzzy match score (0-100)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Organization

Get organization by ID.

Args:

organization_id: Organization ID
current_user: Current authenticated user

Returns:

Organization data with presigned logo URL

Raises:

HTTPException: If organization not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
organization_id
required
string (Organization Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "archived": false,
  • "created_at": "2024-01-01T00:00:00",
  • "description": "An example organization",
  • "name": "Example Org",
  • "normalised_name": "example org",
  • "owner_id": "507f1f77bcf86cd799439012",
  • "project_roles": [
    ],
  • "updated_at": "2024-01-01T00:00:00"
}

Update an organization

Update an existing organization with the provided data

Authorizations:
HTTPBearer
path Parameters
organization_id
required
string (Organization Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Normalised Name (string) or Normalised Name (null) (Normalised Name)
Description (string) or Description (null) (Description)
Logo Url (string) or Logo Url (null) (Logo Url)
Website (string) or Website (null) (Website)
Address (string) or Address (null) (Address)
Phone (string) or Phone (null) (Phone)
Email (string) or Email (null) (Email)
Array of Aliases (strings) or Aliases (null) (Aliases)
Branding (object) or Branding (null) (Branding)
Status (string) or Status (null) (Status)
Array of Project Roles (strings) or Project Roles (null) (Project Roles)
Role (string) or Role (null) (Role)
Archived (boolean) or Archived (null) (Archived)
Archived At (string) or Archived At (null) (Archived At)
Custom Fields (object) or Custom Fields (null) (Custom Fields)
Custom Field Definitions (object) or Custom Field Definitions (null) (Custom Field Definitions)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "normalised_name": "string",
  • "description": "string",
  • "logo_url": "string",
  • "website": "string",
  • "address": "string",
  • "phone": "string",
  • "email": "string",
  • "aliases": [
    ],
  • "branding": { },
  • "status": "string",
  • "project_roles": [
    ],
  • "role": "string",
  • "archived": true,
  • "archived_at": "2019-08-24T14:15:22Z",
  • "custom_fields": { },
  • "custom_field_definitions": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "archived": false,
  • "created_at": "2024-01-01T00:00:00",
  • "description": "An example organization",
  • "name": "Example Org",
  • "normalised_name": "example org",
  • "owner_id": "507f1f77bcf86cd799439012",
  • "project_roles": [
    ],
  • "updated_at": "2024-01-01T00:00:00"
}

Get Organization Members

Get members of an organization.

Args:

org_id: Organization ID
current_user: Current authenticated user

Returns:

List of organization members with membership details

Raises:

HTTPException: If organization not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
org_id
required
string (Org Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Organization Member

Add a member to an organization.

Authorizations:
HTTPBearer
path Parameters
org_id
required
string (Org Id)
query Parameters
send_invite
boolean (Send Invite)
Default: true

If true, send an invitation email to the member

Request Body schema: application/json
required
_id
string (Id)
created_at
string <date-time> (Created At)
updated_at
string <date-time> (Updated At)
Clerk User Id (string) or Clerk User Id (null) (Clerk User Id)

Clerk user ID

name
required
string (Name)

Full name of the user

email
required
string <email> (Email)

Email address of the user

role
string (Role)
Default: "user"

Role of the user

Company (string) or Company (null) (Company)

Company name

Avatar (string) or Avatar (null) (Avatar)
Phone (string) or Phone (null) (Phone)
Department (string) or Department (null) (Department)
Location (string) or Location (null) (Location)
Bio (string) or Bio (null) (Bio)
SocialLinks (object) or null
ProfileSettings (object) or null
archived
boolean (Archived)
Default: false

Whether the user is archived

Archived At (string) or Archived At (null) (Archived At)

Date and time the user was archived

is_signed_up
boolean (Is Signed Up)
Default: true
is_organization_member
boolean (Is Organization Member)
Default: true
organization_id
required
string (Organization Id)

Currently active organization ID (last used becomes default on login)

organization_ids
Array of strings (Organization Ids)

All organizations the user belongs to (denormalized from memberships)

project_ids
Array of strings (Project Ids)
Default: []
status
string (Status)
Default: "pending"
joined_at
string <date-time> (Joined At)
organization_roles
Array of strings (Organization Roles)
Items Enum: "billing_admin" "org_admin" "standard"

Roles within the CURRENT organization (cached from membership)

Responses

Request samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "company": "Example Corp",
  • "created_at": "2024-01-01T00:00:00",
  • "email": "john@example.com",
  • "joined_at": "2024-01-01T00:00:00",
  • "name": "John Doe",
  • "organization_id": "507f1f77bcf86cd799439012",
  • "organization_ids": [
    ],
  • "organization_roles": [
    ],
  • "role": "user",
  • "updated_at": "2024-01-01T00:00:00"
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "company": "Example Corp",
  • "created_at": "2024-01-01T00:00:00",
  • "email": "john@example.com",
  • "joined_at": "2024-01-01T00:00:00",
  • "name": "John Doe",
  • "organization_id": "507f1f77bcf86cd799439012",
  • "organization_ids": [
    ],
  • "organization_roles": [
    ],
  • "role": "user",
  • "updated_at": "2024-01-01T00:00:00"
}

Update Organization Member Roles

Update roles of an organization member.

Args:

org_id: Organization ID
user_id: User ID
roles: New roles for the user
current_user: Current authenticated user

Returns:

Updated membership data

Raises:

HTTPException: If user not authorized or member not found
Authorizations:
HTTPBearer
path Parameters
org_id
required
string (Org Id)
user_id
required
string (User Id)
Request Body schema: application/json
required
Array
string (OrganizationRole)
Enum: "billing_admin" "org_admin" "standard"

Responses

Request samples

Content type
application/json
[
  • "billing_admin"
]

Response samples

Content type
application/json
{
  • "_id": "string",
  • "user_id": "string",
  • "user_name": "string",
  • "user_email": "string",
  • "user_avatar": "string",
  • "roles": [
    ],
  • "joined_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "invited_by": "string"
}

Remove Organization Member

Remove a member from an organization.

Args:

org_id: Organization ID
user_id: User ID
current_user: Current authenticated user

Returns:

Success message

Raises:

HTTPException: If user not authorized or member not found
Authorizations:
HTTPBearer
path Parameters
org_id
required
string (Org Id)
user_id
required
string (User Id)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Upload Organization Logo

Upload an organization logo.

Args:

organization_id: Organization ID
file: The image file to upload
current_user: Current authenticated user

Returns:

Dict containing the logo key and presigned URL

Raises:

HTTPException: If upload fails or user not authorized
Authorizations:
HTTPBearer
path Parameters
organization_id
required
string (Organization Id)
Request Body schema: multipart/form-data
required
file
required
string <binary> (File)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Delete Organization Logo

Delete an organization's logo.

Args:

organization_id: Organization ID
current_user: Current authenticated user

Returns:

Success message

Raises:

HTTPException: If deletion fails or user not authorized
Authorizations:
HTTPBearer
path Parameters
organization_id
required
string (Organization Id)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Upload Organization Logo From Url

Upload an organization logo from a URL.

Downloads the image from the given URL, processes it, and uploads to R2.

Args:

organization_id: Organization ID
body: Request body containing {"url": "https://..."}
current_user: Current authenticated user

Returns:

Dict containing the logo key and presigned URL

Raises:

HTTPException: If download/upload fails or user not authorized
Authorizations:
HTTPBearer
path Parameters
organization_id
required
string (Organization Id)
Request Body schema: application/json
required
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Extract branding colors from a website

Fetch a website's HTML/CSS and extract color values for branding purposes

Authorizations:
HTTPBearer
query Parameters
url
required
string (Url)

Website URL to analyze

Responses

Response samples

Content type
application/json
{ }

Fetch text content from a website

Fetch a website's HTML and return extracted text content for analysis

Authorizations:
HTTPBearer
query Parameters
url
required
string (Url)

Website URL to fetch

Responses

Response samples

Content type
application/json
{ }

Get all projects owned by an organization

Retrieve all projects where organization_id matches the given organization

Authorizations:
HTTPBearer
path Parameters
organization_id
required
string (Organization Id)
query Parameters
page
integer (Page) >= 1
Default: 1

Page number

size
integer (Size) [ 1 .. 100 ]
Default: 10

Number of items per page

Sort By (string) or Sort By (null) (Sort By)
Sort Order (string) or Sort Order (null) (Sort Order)
archived
boolean (Archived)
Default: false

Filter by archived status

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

List My Organizations

List all organizations the current user belongs to.

Returns

List of organizations with membership details
Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Switch Organization

Switch the user's active organization.

Updates the user's current organization context to the specified organization. The user must have an active membership in the target organization.

Args:

organization_id: ID of the organization to switch to
current_user: Current authenticated user

Returns:

The membership details for the new active organization

Raises:

HTTPException: If organization not found or user not a member
Authorizations:
HTTPBearer
path Parameters
organization_id
required
string (Organization Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "organization_id": "string",
  • "organization_name": "string",
  • "organization_description": "string",
  • "roles": [
    ],
  • "joined_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "is_current": false
}

Get Current Organization Context

Get the current organization context.

Returns the user's currently active organization with membership details.

Returns

Current organization with membership details

Raises

HTTPException: If user has no current organization
Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "organization_id": "string",
  • "organization_name": "string",
  • "organization_description": "string",
  • "roles": [
    ],
  • "joined_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "is_current": false
}

Upload organization-level document

Upload a document at the organization level (not tied to a specific project)

Authorizations:
HTTPBearer
path Parameters
organization_id
required
string (Organization Id)
Request Body schema: application/json
required
document_id
required
string (Document Id)

Document ID

Title (string) or Title (null) (Title)

Document title

Document Reference (string) or Document Reference (null) (Document Reference)

Document reference or drawing number

Description (string) or Description (null) (Description)

Document description

DocumentStatus (string) or null

Document status

Revision (string) or Revision (null) (Revision)

Document revision

Category (string) or Category (null) (Category)

Document category

DocumentType (string) or null

Type of document

Content (string) or Content (null) (Content)

Extracted text content from document

Summary (string) or Summary (null) (Summary)

Summary of document

Purpose (string) or Purpose (null) (Purpose)

Purpose of document

Array of Keywords (strings) or Keywords (null) (Keywords)
Default: []

Keywords associated with document

File Path (string) or File Path (null) (File Path)

Path to stored document

File Size (integer) or File Size (null) (File Size)

Size of document in bytes

Mime Type (string) or Mime Type (null) (Mime Type)

MIME type of document

created_at
string <date-time> (Created At)

Creation timestamp

updated_at
string <date-time> (Updated At)

Last update timestamp

Array of objects (Version History)

Version history of document

Thumbnail Image Path (string) or Thumbnail Image Path (null) (Thumbnail Image Path)

Path to thumbnail image

Full Image Path (string) or Full Image Path (null) (Full Image Path)

Path to full image

Error (string) or Error (null) (Error)

Error message if document processing failed

Error Detail (object) or Error Detail (null) (Error Detail)

Error details

filename
required
string (Filename)

Filename of document

r2_path
required
string (R2 Path)

Path to stored document in R2

File Extension (string) or File Extension (null) (File Extension)

File extension without dot (e.g., 'pdf')

FileHandlingTier (string) or null

Processing tier for this file type

Drawing Comparison Id (string) or Drawing Comparison Id (null) (Drawing Comparison Id)

ID of the drawing comparison record, if this document was compared to a previous version

Virtual Document Id (string) or Virtual Document Id (null) (Virtual Document Id)

Reference to the source virtual document if auto-generated from export

Virtual Document Version (integer) or Virtual Document Version (null) (Virtual Document Version)

Version number of the virtual document if auto-generated from export

auto_generated
boolean (Auto Generated)
Default: false

Flag indicating this document was auto-created from a virtual document export

organization_id
required
string (Organization Id)

ID of organization this document belongs to

Project Id (string) or Project Id (null) (Project Id)

Optional project ID if document is also linked to a project

processing_status
required
string (DocumentProcessingStatus)
Enum: "PENDING" "QUEUED" "PROCESSING" "PROCESSED" "FAILED" "DUPLICATE" "PENDING_PROCESSING" "UPLOADED" "ACCEPTED"

Status of document processing

required
object (AssigneeUser)

User who uploaded the document

Responses

Request samples

Content type
application/json
{
  • "document_id": "string",
  • "title": "string",
  • "document_reference": "string",
  • "description": "string",
  • "status": "draft",
  • "revision": "string",
  • "category": "string",
  • "document_type": "brochure",
  • "content": "string",
  • "summary": "string",
  • "purpose": "string",
  • "keywords": [ ],
  • "file_path": "string",
  • "file_size": 0,
  • "mime_type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "version_history": [
    ],
  • "thumbnail_image_path": "string",
  • "full_image_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "filename": "string",
  • "r2_path": "string",
  • "file_extension": "string",
  • "file_handling_tier": "RECORD_ONLY",
  • "drawing_comparison_id": "string",
  • "virtual_document_id": "string",
  • "virtual_document_version": 0,
  • "auto_generated": false,
  • "organization_id": "string",
  • "project_id": "string",
  • "processing_status": "PENDING",
  • "uploaded_by": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "filename": "string",
  • "processing_status": "PENDING",
  • "status": "draft",
  • "r2_path": "string",
  • "chunks_count": 0,
  • "full_image_path": "string",
  • "thumbnail_image_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "metadata": {
    },
  • "latest_version": "string",
  • "is_latest": true,
  • "is_deleted": false,
  • "revision": "string",
  • "purpose": "string",
  • "keywords": [ ],
  • "uploaded_by": {
    },
  • "title": "string",
  • "project_id": "string",
  • "organization_id": "string",
  • "document_reference": "string",
  • "description": "string",
  • "category": "string",
  • "document_type": "brochure",
  • "content": "string",
  • "summary": "string",
  • "file_path": "string",
  • "file_size": 0,
  • "mime_type": "string",
  • "drawing_comparison_id": "string"
}

programme

Programme Management

Manage construction programmes and schedules.

Features:

  • Create and track programme milestones
  • Link programme items to tasks
  • Monitor programme progress

Aggregated programme view (milestones, programme tasks, executions)

Return milestones, programme tasks, and executions for a project.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "milestones": [
    ],
  • "programme_tasks": [
    ],
  • "task_executions": [
    ],
  • "relations": {
    },
  • "timing": {
    },
  • "procurement_actions": [
    ]
}

Milestones with related task executions and planned vs actual data

Return milestones with their related task executions.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Derived procurement schedule from programme tasks

Derive procurement actions from programme tasks for a project.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new programme task

Create a new programme task for a project.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
name
required
string (Name)

Name of the programme task

Description (string) or Description (null) (Description)

Programme task description

project_id
required
string (Project Id)

ID of the project this task belongs to

Planned Start (string) or Planned Start (null) (Planned Start)

Planned start date

Planned End (string) or Planned End (null) (Planned End)

Planned end date

status
string (ProgrammeTaskStatus)
Default: "planned"
Enum: "planned" "in_progress" "completed" "delayed" "cancelled" "on_hold"

Programme task status

priority
string (ProgrammeTaskPriority)
Default: "medium"
Enum: "low" "medium" "high" "urgent"

Programme task priority

completion_percentage
number (Completion Percentage) [ 0 .. 100 ]
Default: 0

Task completion percentage (0-100)

dependencies
Array of strings (Dependencies)

IDs of programme tasks this task depends on

milestone_ids
Array of strings (Milestone Ids)

IDs of milestones related to this programme task

execution_ids
Array of strings (Execution Ids)

IDs of task executions linked to this programme task

Task Template Id (string) or Task Template Id (null) (Task Template Id)

Optional task template ID used to create this programme task

Adjusted Start (string) or Adjusted Start (null) (Adjusted Start)

Start date adjusted after slippage

Adjusted End (string) or Adjusted End (null) (Adjusted End)

End date adjusted after slippage

Import Source (string) or Import Source (null) (Import Source)

Source identifier for imports

object (Metadata)

Sector-specific metadata (procurement, approvals, releases, etc.)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "project_id": "string",
  • "planned_start": "2019-08-24T14:15:22Z",
  • "planned_end": "2019-08-24T14:15:22Z",
  • "status": "planned",
  • "priority": "low",
  • "completion_percentage": 0,
  • "dependencies": [
    ],
  • "milestone_ids": [
    ],
  • "execution_ids": [
    ],
  • "task_template_id": "string",
  • "adjusted_start": "2019-08-24T14:15:22Z",
  • "adjusted_end": "2019-08-24T14:15:22Z",
  • "import_source": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "project_id": "string",
  • "planned_start": "2019-08-24T14:15:22Z",
  • "planned_end": "2019-08-24T14:15:22Z",
  • "status": "planned",
  • "priority": "low",
  • "completion_percentage": 0,
  • "dependencies": [
    ],
  • "milestone_ids": [
    ],
  • "execution_ids": [
    ],
  • "task_template_id": "string",
  • "adjusted_start": "2019-08-24T14:15:22Z",
  • "adjusted_end": "2019-08-24T14:15:22Z",
  • "import_source": "string",
  • "metadata": { },
  • "created_by": "string",
  • "updated_by": "string"
}

List all programme tasks for a project

List all programme tasks for a specific project.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single programme task

Retrieve a single programme task by ID.

Authorizations:
HTTPBearer
path Parameters
task_id
required
string (Task Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "project_id": "string",
  • "planned_start": "2019-08-24T14:15:22Z",
  • "planned_end": "2019-08-24T14:15:22Z",
  • "status": "planned",
  • "priority": "low",
  • "completion_percentage": 0,
  • "dependencies": [
    ],
  • "milestone_ids": [
    ],
  • "execution_ids": [
    ],
  • "task_template_id": "string",
  • "adjusted_start": "2019-08-24T14:15:22Z",
  • "adjusted_end": "2019-08-24T14:15:22Z",
  • "import_source": "string",
  • "metadata": { },
  • "created_by": "string",
  • "updated_by": "string"
}

Update a programme task

Update an existing programme task.

Authorizations:
HTTPBearer
path Parameters
task_id
required
string (Task Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Planned Start (string) or Planned Start (null) (Planned Start)
Planned End (string) or Planned End (null) (Planned End)
ProgrammeTaskStatus (string) or null
ProgrammeTaskPriority (string) or null
Completion Percentage (number) or Completion Percentage (null) (Completion Percentage)
Array of Dependencies (strings) or Dependencies (null) (Dependencies)
Array of Milestone Ids (strings) or Milestone Ids (null) (Milestone Ids)
Array of Execution Ids (strings) or Execution Ids (null) (Execution Ids)
Task Template Id (string) or Task Template Id (null) (Task Template Id)
Adjusted Start (string) or Adjusted Start (null) (Adjusted Start)
Adjusted End (string) or Adjusted End (null) (Adjusted End)
Import Source (string) or Import Source (null) (Import Source)
Metadata (object) or Metadata (null) (Metadata)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "planned_start": "2019-08-24T14:15:22Z",
  • "planned_end": "2019-08-24T14:15:22Z",
  • "status": "planned",
  • "priority": "low",
  • "completion_percentage": 0,
  • "dependencies": [
    ],
  • "milestone_ids": [
    ],
  • "execution_ids": [
    ],
  • "task_template_id": "string",
  • "adjusted_start": "2019-08-24T14:15:22Z",
  • "adjusted_end": "2019-08-24T14:15:22Z",
  • "import_source": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "project_id": "string",
  • "planned_start": "2019-08-24T14:15:22Z",
  • "planned_end": "2019-08-24T14:15:22Z",
  • "status": "planned",
  • "priority": "low",
  • "completion_percentage": 0,
  • "dependencies": [
    ],
  • "milestone_ids": [
    ],
  • "execution_ids": [
    ],
  • "task_template_id": "string",
  • "adjusted_start": "2019-08-24T14:15:22Z",
  • "adjusted_end": "2019-08-24T14:15:22Z",
  • "import_source": "string",
  • "metadata": { },
  • "created_by": "string",
  • "updated_by": "string"
}

Delete a programme task

Delete a programme task.

Authorizations:
HTTPBearer
path Parameters
task_id
required
string (Task Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get programme tasks optimized for Gantt chart rendering

Retrieve programme tasks in an optimized format for Gantt chart rendering.

Returns task data with:

  • Effective start/end dates (adjusted for slippage or planned)
  • Critical path information
  • Dependency relationships
  • Minimal payload for efficient frontend rendering

Args:

project_id: Project ID to fetch tasks for
current_user: Current authenticated user

Returns:

List of tasks optimized for Gantt chart display
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Propagate slippage from a delayed task

Propagate slippage when a task completes late.

When a task completes later than planned, this endpoint calculates the delay and automatically adjusts the start and end dates for all dependent tasks.

Args:

task_id: ID of the task that slipped
actual_completion: Actual completion datetime of the task
current_user: Current authenticated user

Returns:

Dictionary with:
- affected_task_ids: List of task IDs that were adjusted
- delay_days: Number of days the task slipped
- updated_count: Number of tasks updated in database
Authorizations:
HTTPBearer
path Parameters
task_id
required
string (Task Id)
query Parameters
actual_completion
required
string <date-time> (Actual Completion)

Responses

Response samples

Content type
application/json
{ }

Import programme tasks from CSV

Import programme tasks from a CSV file.

Expected CSV columns (case-insensitive):

  • name (required)
  • description
  • planned_start or start_date
  • planned_end or end_date
  • status
  • priority
  • dependencies (comma-separated task names)
  • completion_percentage or progress
  • Any additional columns are stored as metadata

Args:

project_id: Project ID to import tasks into
file: CSV file upload
current_user: Current authenticated user

Returns:

Dictionary with:
- imported_count: Number of tasks successfully imported
- errors: List of error messages for failed rows
- task_ids: List of created task IDs
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: multipart/form-data
required
file
required
string <binary> (File)

Responses

Response samples

Content type
application/json
{ }

Import programme tasks from Microsoft Project XML

Import programme tasks from Microsoft Project XML exports.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: multipart/form-data
required
file
required
string <binary> (File)

Responses

Response samples

Content type
application/json
{ }

Export programme tasks to Microsoft Project XML

Export programme tasks to Microsoft Project XML format.

Exports all programme tasks for the specified project in MSP XML format, which can be imported into Microsoft Project or other compatible tools.

The export preserves:

  • Task names, descriptions, and dates
  • Completion percentages
  • Dependencies with their types (FS, SS, FF, SF)
  • Metadata including WBS levels, durations, constraints, and calendars
  • MSP UIDs for round-trip compatibility with previously imported data

Args:

project_id: Project ID to export tasks from
current_user: Current authenticated user

Returns:

XML file as downloadable response
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

project-defaults

Project Defaults

Configure default settings and templates for projects.

Features:

  • Set default document categories and tags
  • Configure default task templates
  • Manage project-level presets

Capture Project Defaults

Capture defaults from the specified project.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
name
required
string (Name)
Description (string) or Description (null) (Description)
include_reports
boolean (Include Reports)
Default: true
report_content_mode
string (ReportContentMode)
Default: "placeholder"
Enum: "original" "placeholder"

How report content should be captured for blueprints.

Placeholder Text (string) or Placeholder Text (null) (Placeholder Text)
include_forms
boolean (Include Forms)
Default: true
Metadata (object) or Metadata (null) (Metadata)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "include_reports": true,
  • "report_content_mode": "original",
  • "placeholder_text": "string",
  • "include_forms": true,
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "organization_id": "string",
  • "source_project_id": "string",
  • "created_by": "string",
  • "description": "string",
  • "custom_fields": { },
  • "custom_field_definitions": {
    },
  • "template_snapshots": [
    ],
  • "report_blueprints": [
    ],
  • "form_template_snapshots": [
    ],
  • "metadata": { }
}

List Project Defaults

List defaults for the current user's organization.

Args:

include_public: If True, also return generic/public project defaults (default: True)
db: Database connection
current_user: Authenticated organization user
Authorizations:
HTTPBearer
query Parameters
include_public
boolean (Include Public)
Default: true

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Project Defaults

Retrieve a specific defaults snapshot.

Authorizations:
HTTPBearer
path Parameters
defaults_id
required
string (Defaults Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "organization_id": "string",
  • "source_project_id": "string",
  • "created_by": "string",
  • "description": "string",
  • "custom_fields": { },
  • "custom_field_definitions": {
    },
  • "template_snapshots": [
    ],
  • "report_blueprints": [
    ],
  • "form_template_snapshots": [
    ],
  • "metadata": { }
}

Delete Project Defaults

Delete a defaults snapshot.

Authorizations:
HTTPBearer
path Parameters
defaults_id
required
string (Defaults Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Apply Project Defaults

Apply a defaults snapshot to an existing project.

Authorizations:
HTTPBearer
path Parameters
defaults_id
required
string (Defaults Id)
Request Body schema: application/json
required
project_id
required
string (Project Id)

Responses

Request samples

Content type
application/json
{
  • "project_id": "string"
}

Response samples

Content type
application/json
{
  • "custom_fields_added": 0,
  • "custom_field_definitions_added": 0,
  • "templates_cloned": 0,
  • "template_references_tracked": 0,
  • "reports_created": 0,
  • "form_templates_cloned": 0,
  • "form_template_references_tracked": 0
}

projects

Project Management

Manage construction projects and their settings.

Features:

  • Create and configure projects
  • Manage project team members and permissions
  • Set project-level defaults and configurations
  • Track project milestones and progress

List all projects

Retrieve a list of all projects with pagination and sorting

Authorizations:
HTTPBearer
query Parameters
page
integer (Page) >= 1
Default: 1

Page number

size
integer (Size) [ 1 .. 100 ]
Default: 10

Number of items per page

Sort By (string) or Sort By (null) (Sort By)
Sort Order (string) or Sort Order (null) (Sort Order)
archived
boolean (Archived)
Default: false

Filter by archived status

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Create a new project

Create a new project with the provided data

Authorizations:
HTTPBearer
Request Body schema: application/json
required
name
required
string (Name)

Name of the project

Project Reference (string) or Project Reference (null) (Project Reference)

Project reference identifier

Logo (string) or Logo (null) (Logo)

URL to project logo

Location (string) or Location (null) (Location)

Project location

Latitude (number) or Latitude (null) (Latitude)

Latitude derived from the project location

Longitude (number) or Longitude (null) (Longitude)

Longitude derived from the project location

ProjectPhaseEnum (string) or null

Current project phase

Cde (string) or Cde (null) (Cde)

Project CDE

Cde Color (string) or Cde Color (null) (Cde Color)

CDE color code

Members (integer) or Members (null) (Members)

Number of project members

StatusEnum (string) or null
Default: "active"

Project status: active, archived, or available

Description (string) or Description (null) (Description)

Project description

Start Date (string) or Start Date (null) (Start Date)

Project start date

End Date (string) or End Date (null) (End Date)

Project end date

Budget (number) or Budget (null) (Budget)

Project budget

Currency (string) or Currency (null) (Currency)

Budget currency

Array of Tags (strings) or Tags (null) (Tags)

Project tags

archived
boolean (Archived)
Default: false

Whether the project is archived

Archived At (string) or Archived At (null) (Archived At)

Date and time the project was archived

Completion Percentage (number) or Completion Percentage (null) (Completion Percentage)

Project completion percentage

organization_id
required
string (Organization Id)

ID of the organization this project belongs to

License Id (string) or License Id (null) (License Id)

ID of the license assigned to this project

ProjectSettings (object) or null

Settings for the project

object (Custom Fields)

Custom key-value fields for organization-specific project data (e.g., project_number, client_name, contract_id)

object (Custom Field Definitions)

Schema definitions for custom fields at project level. These override or extend organization-level definitions. Keys should match keys in custom_fields.

created_by
required
string (Created By)

ID of the user creating the project

Defaults Id (string) or Defaults Id (null) (Defaults Id)

Optional project defaults snapshot to apply after creation

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "project_reference": "string",
  • "logo": "string",
  • "location": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "phase": "Initiation / Feasibility",
  • "cde": "string",
  • "cde_color": "string",
  • "members": 0,
  • "status": "active",
  • "description": "string",
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z",
  • "budget": 0,
  • "currency": "string",
  • "tags": [
    ],
  • "archived": false,
  • "archived_at": "2019-08-24T14:15:22Z",
  • "completion_percentage": 0,
  • "organization_id": "string",
  • "license_id": "string",
  • "project_settings": {
    },
  • "custom_fields": { },
  • "custom_field_definitions": {
    },
  • "created_by": "string",
  • "defaults_id": "string"
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "archived": false,
  • "created_at": "2024-01-01T00:00:00",
  • "created_by": "507f1f77bcf86cd799439013",
  • "description": "An example project",
  • "name": "Example Project",
  • "organization_id": "507f1f77bcf86cd799439012",
  • "status": "active",
  • "tags": [
    ],
  • "updated_at": "2024-01-01T00:00:00"
}

Get project by ID

Retrieve a specific project by its ID

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "archived": false,
  • "created_at": "2024-01-01T00:00:00",
  • "created_by": "507f1f77bcf86cd799439013",
  • "description": "An example project",
  • "name": "Example Project",
  • "organization_id": "507f1f77bcf86cd799439012",
  • "status": "active",
  • "tags": [
    ],
  • "updated_at": "2024-01-01T00:00:00"
}

Update a project

Update an existing project with the provided data

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Project Reference (string) or Project Reference (null) (Project Reference)
Logo (string) or Logo (null) (Logo)
Location (string) or Location (null) (Location)
Latitude (number) or Latitude (null) (Latitude)
Longitude (number) or Longitude (null) (Longitude)
ProjectPhaseEnum (string) or null
Cde (string) or Cde (null) (Cde)
Cde Color (string) or Cde Color (null) (Cde Color)
Members (integer) or Members (null) (Members)
Status (string) or Status (null) (Status)
Description (string) or Description (null) (Description)
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
Budget (number) or Budget (null) (Budget)
Currency (string) or Currency (null) (Currency)
Array of Tags (strings) or Tags (null) (Tags)
Completion Percentage (number) or Completion Percentage (null) (Completion Percentage)
Updated By (string) or Updated By (null) (Updated By)
Archived (boolean) or Archived (null) (Archived)
Archived At (string) or Archived At (null) (Archived At)
Custom Fields (object) or Custom Fields (null) (Custom Fields)
Custom Field Definitions (object) or Custom Field Definitions (null) (Custom Field Definitions)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "project_reference": "string",
  • "logo": "string",
  • "location": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "phase": "Initiation / Feasibility",
  • "cde": "string",
  • "cde_color": "string",
  • "members": 0,
  • "status": "string",
  • "description": "string",
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z",
  • "budget": 0,
  • "currency": "string",
  • "tags": [
    ],
  • "completion_percentage": 0,
  • "updated_by": "string",
  • "archived": true,
  • "archived_at": "2019-08-24T14:15:22Z",
  • "custom_fields": { },
  • "custom_field_definitions": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "archived": false,
  • "created_at": "2024-01-01T00:00:00",
  • "created_by": "507f1f77bcf86cd799439013",
  • "description": "An example project",
  • "name": "Example Project",
  • "organization_id": "507f1f77bcf86cd799439012",
  • "status": "active",
  • "tags": [
    ],
  • "updated_at": "2024-01-01T00:00:00"
}

Delete a project

Delete an existing project

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Get project members

Get all members of a project with pagination, sorting, and their membership info

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
query Parameters
page
integer (Page) >= 1
Default: 1

Page number

size
integer (Size) [ 1 .. 100 ]
Default: 10

Number of items per page

Sort By (string) or Sort By (null) (Sort By)
Sort Order (string) or Sort Order (null) (Sort Order)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Add Project Member

Create or invite a project user and optionally configure their membership in a single call.

Args:

project_id: ID of the project
payload: Payload containing user data and membership details
request: FastAPI request object for accessing raw request body
db: MongoDB database instance
current_user: Current authenticated user

Returns:

Project member with membership information

Raises:

HTTPException: If project not found, user not authorized, or user already a member
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
Any of
required
object (ProjectUser-Input)

User profile data to create or update within the project context

ProjectMembershipRequest (object) or null

Optional membership configuration to apply for this user on the project

Organization Id (string) or Organization Id (null) (Organization Id)

Organization that this user should belong to for the project. If provided, the user will be added to the organization's member list.

Responses

Request samples

Content type
application/json
Example
{
  • "member": {
    },
  • "membership": {
    },
  • "organization_id": "string"
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "clerk_user_id": "user_2vJxJEQkkigpll5LMweU8vcMXoL",
  • "company": "Example Corp",
  • "created_at": "2024-01-01T00:00:00",
  • "email": "john@example.com",
  • "joined_at": "2024-01-01T00:00:00",
  • "membership": {
    },
  • "name": "John Doe",
  • "organization": {
    },
  • "organization_id": "507f1f77bcf86cd799439015",
  • "project_ids": [
    ],
  • "role": "user",
  • "status": "active",
  • "updated_at": "2024-01-01T00:00:00"
}

Remove Project Member

Remove a member from a project.

Args:

project_id: Project ID
user_id: User ID
db: MongoDB database instance
current_user: Current authenticated user

Returns:

Success message

Raises:

HTTPException: If user not authorized or member not found
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
user_id
required
string (User Id)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Update a project member

Update a project member's information. Admins can update any field except email, while users can only update their own information.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
user_id
required
string (User Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Avatar (string) or Avatar (null) (Avatar)
Company (string) or Company (null) (Company)
Phone (string) or Phone (null) (Phone)
Department (string) or Department (null) (Department)
Location (string) or Location (null) (Location)
Bio (string) or Bio (null) (Bio)
SocialLinks (object) or null
Status (string) or Status (null) (Status)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "avatar": "string",
  • "company": "string",
  • "phone": "string",
  • "department": "string",
  • "location": "string",
  • "bio": "string",
  • "social_links": {
    },
  • "status": "string"
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "clerk_user_id": "user_2vJxJEQkkigpll5LMweU8vcMXoL",
  • "company": "Example Corp",
  • "created_at": "2024-01-01T00:00:00",
  • "email": "john@example.com",
  • "name": "John Doe",
  • "role": "user",
  • "updated_at": "2024-01-01T00:00:00"
}

Get project memberships

Get all memberships for a project with user information

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
query Parameters
page
integer (Page) >= 1
Default: 1

Page number

size
integer (Size) [ 1 .. 100 ]
Default: 10

Number of items per page

Sort By (string) or Sort By (null) (Sort By)
Sort Order (string) or Sort Order (null) (Sort Order)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Add a user to a project

Add a user to a project with a specific role

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
user_id
required
string (User Id)

ID of the user

Organization Id (string) or Organization Id (null) (Organization Id)

ID of the organization the membership should be associated with

role
string (ProjectRole)
Default: "member"
Enum: "admin" "member" "viewer"

Role of the user in the project

status
string (Status)
Default: "active"

Status of the membership: active, inactive, pending

Array of Project Roles (strings) or Project Roles (null) (Project Roles)

Organization-defined project role labels to assign with this membership

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "organization_id": "string",
  • "role": "admin",
  • "status": "active",
  • "project_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "created_at": "2024-01-01T00:00:00",
  • "joined_at": "2024-01-01T00:00:00",
  • "organization_id": "507f1f77bcf86cd799439014",
  • "project_id": "507f1f77bcf86cd799439013",
  • "project_roles": [
    ],
  • "role": "member",
  • "status": "active",
  • "updated_at": "2024-01-01T00:00:00",
  • "user_id": "507f1f77bcf86cd799439012"
}

Update a project membership

Update a user's role or status in a project

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
membership_id
required
string (Membership Id)
Request Body schema: application/json
required
Organization Id (string) or Organization Id (null) (Organization Id)
ProjectRole (string) or null
Status (string) or Status (null) (Status)
Array of Project Roles (strings) or Project Roles (null) (Project Roles)

Responses

Request samples

Content type
application/json
{
  • "organization_id": "string",
  • "role": "admin",
  • "status": "string",
  • "project_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "created_at": "2024-01-01T00:00:00",
  • "joined_at": "2024-01-01T00:00:00",
  • "organization_id": "507f1f77bcf86cd799439014",
  • "project_id": "507f1f77bcf86cd799439013",
  • "project_roles": [
    ],
  • "role": "member",
  • "status": "active",
  • "updated_at": "2024-01-01T00:00:00",
  • "user_id": "507f1f77bcf86cd799439012"
}

Remove a user from a project

Remove a user's membership from a project

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
membership_id
required
string (Membership Id)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Create a project invitation

Create a new project invitation and send invitation email. Requires org_admin role.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
email
required
string (Email)

Email of the user to invite

Name (string) or Name (null) (Name)

Name of the invitee

role
string (Role)
Default: "member"

Role to assign: admin, member, viewer

Array of Project Roles (strings) or Project Roles (null) (Project Roles)

Project role labels

Personal Message (string) or Personal Message (null) (Personal Message)

Personal message to include in invitation

expires_in_days
integer (Expires In Days) [ 1 .. 30 ]
Default: 7

Days until invitation expires

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "name": "string",
  • "role": "member",
  • "project_roles": [
    ],
  • "personal_message": "string",
  • "expires_in_days": 7
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "invitation_token": "string",
  • "project_id": "string",
  • "project_name": "string",
  • "invitee_email": "string",
  • "invitee_name": "string",
  • "inviter_name": "string",
  • "organization_name": "string",
  • "role": "string",
  • "project_roles": [
    ],
  • "status": "pending",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "email_sent_at": "2019-08-24T14:15:22Z",
  • "email_sent_count": 0,
  • "last_resent_at": "2019-08-24T14:15:22Z",
  • "personal_message": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

List project invitations

List all invitations for a project. Optionally filter by status. Requires org_admin role.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
query Parameters
InvitationStatus (string) or Status (null) (Status)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Resend project invitation

Resend invitation email (manual reminder). Requires org_admin role.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
invitation_id
required
string (Invitation Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "invitation_token": "string",
  • "project_id": "string",
  • "project_name": "string",
  • "invitee_email": "string",
  • "invitee_name": "string",
  • "inviter_name": "string",
  • "organization_name": "string",
  • "role": "string",
  • "project_roles": [
    ],
  • "status": "pending",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "email_sent_at": "2019-08-24T14:15:22Z",
  • "email_sent_count": 0,
  • "last_resent_at": "2019-08-24T14:15:22Z",
  • "personal_message": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Revoke project invitation

Revoke a pending invitation. Requires org_admin role.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
invitation_id
required
string (Invitation Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

public-access

public-access endpoints

Get Share Preview

Get preview metadata for a share (for social cards/SEO).

Args:

share_token: Share token
db: Database client

Returns:

Preview metadata

Raises:

HTTPException: If share not found or revoked
path Parameters
share_token
required
string (Share Token)

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "resource_type": "string",
  • "access_type": "string",
  • "requires_email": true,
  • "requires_password": true,
  • "og_image_url": "string"
}

Access Public Share

Access a publicly shared resource (for public/unrestricted shares).

Args:

share_token: Share token
request: FastAPI request
db: Database client

Returns:

Resource data and metadata

Raises:

HTTPException: If share not found, expired, or requires verification
path Parameters
share_token
required
string (Share Token)

Responses

Response samples

Content type
application/json
{ }

Verify Share Access

Verify access for email-gated or password-protected shares.

Args:

share_token: Share token
verification: Verification credentials
request: FastAPI request
db: Database client

Returns:

Resource data and metadata

Raises:

HTTPException: If verification fails
path Parameters
share_token
required
string (Share Token)
Request Body schema: application/json
required
Email (string) or Email (null) (Email)
Password (string) or Password (null) (Password)

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{ }

Short Code Redirect

Resolve short code to full share token.

Args:

short_code: Short code
db: Database client

Returns:

Redirect information

Raises:

HTTPException: If short code not found
path Parameters
short_code
required
string (Short Code)

Responses

Response samples

Content type
application/json
{ }

Get project invitation info

Get invitation details by token (public, no auth required).

path Parameters
token
required
string (Token)

Responses

Response samples

Content type
application/json
{
  • "valid": true,
  • "status": "string",
  • "project_name": "string",
  • "organization_name": "string",
  • "inviter_name": "string",
  • "invitee_email": "string",
  • "role": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "is_expired": true
}

Accept project invitation

Accept a project invitation via magic link. If user is authenticated, uses their account. If not authenticated, creates a pending user account.

Authorizations:
HTTPBearer
path Parameters
token
required
string (Token)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "redirect_url": "string",
  • "project_id": "string",
  • "project_name": "string",
  • "requires_signup": true,
  • "user_created": false
}

Get Shared Resource

Get a shared resource by token (unified endpoint).

This endpoint handles all share types and returns the appropriate data based on the resource_type. For form instances, it returns enriched data including schema and UI schema. For other types, it returns the resource.

Args:

share_token: Share token (e.g., ps_abc123...)
request: FastAPI request
db: Database client

Returns:

Resource data with appropriate structure based on resource type

Raises:

HTTPException: If share not found, expired, or access denied
path Parameters
share_token
required
string (Share Token)

Responses

Response samples

Content type
application/json
{ }

public-forms

public-forms endpoints

Get Public Form

Get form schema for public access via share token.

Args:

share_token: Share token for the form instance
request: FastAPI request
db: Database client

Returns:

Form schema and instance metadata

Raises:

HTTPException: If share not found, expired, or access denied
path Parameters
share_token
required
string (Share Token)

Responses

Response samples

Content type
application/json
{ }

Presign Public Attachment Upload

Presign an attachment upload for a public form share.

path Parameters
share_token
required
string (Share Token)
Request Body schema: application/json
required
field_id
required
string (Field Id)
filename
required
string (Filename)
content_type
required
string (Content Type)
size_bytes
required
integer (Size Bytes)
Completer Email (string) or Completer Email (null) (Completer Email)

Responses

Request samples

Content type
application/json
{
  • "field_id": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "completer_email": "string"
}

Response samples

Content type
application/json
{
  • "attachment_id": "string",
  • "upload_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "r2_key": "string",
  • "required_headers": {
    }
}

Confirm Public Attachment Upload

Confirm a public attachment upload and return thumbnail info if available.

path Parameters
share_token
required
string (Share Token)
attachment_id
required
string (Attachment Id)
Request Body schema: application/json
required
Checksum (string) or Checksum (null) (Checksum)
Completer Email (string) or Completer Email (null) (Completer Email)

Responses

Request samples

Content type
application/json
{
  • "checksum": "string",
  • "completer_email": "string"
}

Response samples

Content type
application/json
{
  • "attachment_id": "string",
  • "r2_key": "string",
  • "thumbnail_url": "string",
  • "status": "ready"
}

Get Public Attachment Urls

Get presigned download URLs for a public form attachment.

path Parameters
share_token
required
string (Share Token)
attachment_id
required
string (Attachment Id)
query Parameters
Completer Email (string) or Completer Email (null) (Completer Email)

Responses

Response samples

Content type
application/json
{
  • "download_url": "string",
  • "thumbnail_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Submit Public Form

Submit a form via public share token.

Args:

share_token: Share token for the form instance
request_data: Form submission data
request: FastAPI request
db: Database client

Returns:

Submission result

Raises:

HTTPException: If share not found, expired, or submission fails
path Parameters
share_token
required
string (Share Token)
Request Body schema: application/json
required
required
object (Values)
completer_name
required
string (Completer Name)
completer_email
required
string (Completer Email)

Responses

Request samples

Content type
application/json
{
  • "values": { },
  • "completer_name": "string",
  • "completer_email": "string"
}

Response samples

Content type
application/json
{ }

Get Public Section Progress

Get section progress for a workflow form via public share token.

Args:

share_token: Share token for the form instance
request: FastAPI request
db: Database client

Returns:

List of section progress summaries

Raises:

HTTPException: If share not found, expired, or not a workflow form
path Parameters
share_token
required
string (Share Token)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Complete Public Section

Complete a section of a workflow form via public share token.

Args:

share_token: Share token for the form instance
section_id: Section to complete
request_data: Section completion data
request: FastAPI request
db: Database client

Returns:

Section completion record

Raises:

HTTPException: If share not found, expired, or completion fails
path Parameters
share_token
required
string (Share Token)
section_id
required
string (Section Id)
Request Body schema: application/json
required
required
object (Values)
completer_name
required
string (Completer Name)
completer_email
required
string (Completer Email)
Signature Data (string) or Signature Data (null) (Signature Data)

Responses

Request samples

Content type
application/json
{
  • "values": { },
  • "completer_name": "string",
  • "completer_email": "string",
  • "signature_data": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "instance_id": "string",
  • "submission_id": "string",
  • "section_id": "string",
  • "section_order": 0,
  • "revision_number": 0,
  • "completed_by_user_id": "string",
  • "completed_by_external": {
    },
  • "signature": {
    },
  • "status": "completed",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "previous_completion_id": "string",
  • "amendment_note": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

public-reports

public-reports endpoints

Get Public Report

Get report data for public access via share token.

Args:

share_token: Share token for the report
request: FastAPI request
db: Database client

Returns:

Formatted report data with branding

Raises:

HTTPException: If share not found, expired, or access denied
path Parameters
share_token
required
string (Share Token)

Responses

Response samples

Content type
application/json
{
  • "report_id": "string",
  • "title": "string",
  • "content": "string",
  • "category": "Environmental",
  • "format": "Text",
  • "tags": [
    ],
  • "version": 0,
  • "created_at": "string",
  • "updated_at": "string",
  • "created_by_name": "string",
  • "project": { },
  • "organization": { },
  • "share_info": { }
}

Verify Report Access

Verify access for email-gated or password-protected report shares.

Args:

share_token: Share token for the report
verification: Verification credentials
request: FastAPI request
db: Database client

Returns:

Formatted report data with branding

Raises:

HTTPException: If verification fails
path Parameters
share_token
required
string (Share Token)
Request Body schema: application/json
required
Email (string) or Email (null) (Email)
Password (string) or Password (null) (Password)

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "report_id": "string",
  • "title": "string",
  • "content": "string",
  • "category": "Environmental",
  • "format": "Text",
  • "tags": [
    ],
  • "version": 0,
  • "created_at": "string",
  • "updated_at": "string",
  • "created_by_name": "string",
  • "project": { },
  • "organization": { },
  • "share_info": { }
}

public-shares

public-shares endpoints

Create Share

Create a new public share for a resource.

Args:

request: Share creation request
db: Database client
current_user: Authenticated user

Returns:

Created share details

Raises:

HTTPException: If validation fails or resource not found
Authorizations:
HTTPBearer
Request Body schema: application/json
required
resource_type
required
string (ShareResourceType)
Enum: "report" "task" "document" "uploaded_document" "project_summary" "milestone" "form_instance" "form_submission"

Resource types that can be shared publicly.

resource_id
required
string (Resource Id)
access_type
string (ShareAccessType)
Default: "public"
Enum: "public" "email_gated" "password_protected" "domain_restricted"

Access type for public shares.

allowed_emails
Array of strings (Allowed Emails)
allowed_domains
Array of strings (Allowed Domains)
permission_levels
Array of strings (Permission Levels)
Items Enum: "view" "comment" "download" "print"
Password (string) or Password (null) (Password)
Expires In Days (integer) or Expires In Days (null) (Expires In Days)
Max Access Count (integer) or Max Access Count (null) (Max Access Count)
Short Code (string) or Short Code (null) (Short Code)
Custom Title (string) or Custom Title (null) (Custom Title)
Custom Description (string) or Custom Description (null) (Custom Description)
Project Id (string) or Project Id (null) (Project Id)

Responses

Request samples

Content type
application/json
{
  • "resource_type": "report",
  • "resource_id": "string",
  • "access_type": "public",
  • "allowed_emails": [
    ],
  • "allowed_domains": [
    ],
  • "permission_levels": [
    ],
  • "password": "string",
  • "expires_in_days": 1,
  • "max_access_count": 1,
  • "short_code": "string",
  • "custom_title": "string",
  • "custom_description": "string",
  • "project_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "share_token": "string",
  • "short_code": "string",
  • "resource_type": "string",
  • "resource_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "access_type": "string",
  • "permission_levels": [
    ],
  • "expires_at": "string",
  • "max_access_count": 0,
  • "is_active": true,
  • "access_count": 0,
  • "unique_accessor_count": 0,
  • "last_accessed_at": "string",
  • "created_at": "string",
  • "created_by_name": "string",
  • "share_path": "string"
}

List Shares

List shares created in the user's organization.

Args:

resource_type: Filter by resource type
resource_id: Filter by specific resource
is_active: Filter by active status
page: Page number
size: Items per page
db: Database client
current_user: Authenticated user

Returns:

Paginated list of shares
Authorizations:
HTTPBearer
query Parameters
ShareResourceType (string) or Resource Type (null) (Resource Type)
Resource Id (string) or Resource Id (null) (Resource Id)
Is Active (boolean) or Is Active (null) (Is Active)
Default: true
page
integer (Page) >= 1
Default: 1
size
integer (Size) [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Get Share

Get details of a specific share.

Args:

share_id: Share ID
db: Database client
current_user: Authenticated user

Returns:

Share details

Raises:

HTTPException: If share not found
Authorizations:
HTTPBearer
path Parameters
share_id
required
string (Share Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "share_token": "string",
  • "short_code": "string",
  • "resource_type": "string",
  • "resource_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "access_type": "string",
  • "permission_levels": [
    ],
  • "expires_at": "string",
  • "max_access_count": 0,
  • "is_active": true,
  • "access_count": 0,
  • "unique_accessor_count": 0,
  • "last_accessed_at": "string",
  • "created_at": "string",
  • "created_by_name": "string",
  • "share_path": "string"
}

Revoke Share

Revoke a share.

Args:

share_id: Share ID to revoke
reason: Optional revocation reason
db: Database client
current_user: Authenticated user

Raises:

HTTPException: If share not found or already revoked
Authorizations:
HTTPBearer
path Parameters
share_id
required
string (Share Id)
query Parameters
Reason (string) or Reason (null) (Reason)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Batch Revoke Shares

Batch revoke multiple shares.

Args:

request: Batch revoke request
db: Database client
current_user: Authenticated user

Returns:

Results of batch operation
Authorizations:
HTTPBearer
Request Body schema: application/json
required
share_ids
required
Array of strings (Share Ids)
Reason (string) or Reason (null) (Reason)

Responses

Request samples

Content type
application/json
{
  • "share_ids": [
    ],
  • "reason": "string"
}

Response samples

Content type
application/json
{ }

Get Share Analytics

Get analytics for a share.

Args:

share_id: Share ID
days: Number of days to analyze
db: Database client
current_user: Authenticated user

Returns:

Analytics data

Raises:

HTTPException: If share not found
Authorizations:
HTTPBearer
path Parameters
share_id
required
string (Share Id)
query Parameters
days
integer (Days) [ 1 .. 365 ]
Default: 30

Responses

Response samples

Content type
application/json
{ }

qr-codes

qr-codes endpoints

Create Qr Code

Generate a new QR code for a resource.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
resource_type
required
string (QRCodeResourceType)
Enum: "form_instance" "public_share" "project" "document" "report"

Type of resource the QR code links to.

resource_id
required
string (Resource Id)
display_name
required
string (Display Name)
target_url
required
string (Target Url)
Project Id (string) or Project Id (null) (Project Id)
include_logo
boolean (Include Logo)
Default: true
object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "resource_type": "form_instance",
  • "resource_id": "string",
  • "display_name": "string",
  • "target_url": "string",
  • "project_id": "string",
  • "include_logo": true,
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "resource_type": "form_instance",
  • "resource_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "display_name": "string",
  • "target_url": "string",
  • "storage_key": "string",
  • "qr_code_url": "string",
  • "include_logo": true,
  • "access_count": 0,
  • "last_accessed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Qr Codes

List QR codes for the organization.

Authorizations:
HTTPBearer
query Parameters
QRCodeResourceType (string) or Resource Type (null) (Resource Type)
Project Id (string) or Project Id (null) (Project Id)
page
integer (Page) >= 1
Default: 1
size
integer (Size) [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Get Qr Code

Get a QR code by ID.

Authorizations:
HTTPBearer
path Parameters
qr_code_id
required
string (Qr Code Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "resource_type": "form_instance",
  • "resource_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "display_name": "string",
  • "target_url": "string",
  • "storage_key": "string",
  • "qr_code_url": "string",
  • "include_logo": true,
  • "access_count": 0,
  • "last_accessed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Qr Code

Delete a QR code.

Authorizations:
HTTPBearer
path Parameters
qr_code_id
required
string (Qr Code Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Qr Code Image

Get QR code image directly (PNG).

Authorizations:
HTTPBearer
path Parameters
qr_code_id
required
string (Qr Code Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Generate Form Instance Qr Code

Generate a QR code for a form instance.

If a QR code already exists for this instance, returns the existing one.

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)
Request Body schema: application/json
Any of
Display Name (string) or Display Name (null) (Display Name)

Custom display name (defaults to form title)

include_logo
boolean (Include Logo)
Default: true

Include planops logo in center

Responses

Request samples

Content type
application/json
Example
{
  • "display_name": "string",
  • "include_logo": true
}

Response samples

Content type
application/json
{
  • "qr_code_id": "string",
  • "qr_code_url": "string",
  • "target_url": "string",
  • "display_name": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Get Form Instance Qr Code

Get the QR code for a form instance if one exists.

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)

Responses

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "resource_type": "form_instance",
  • "resource_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "display_name": "string",
  • "target_url": "string",
  • "storage_key": "string",
  • "qr_code_url": "string",
  • "include_logo": true,
  • "access_count": 0,
  • "last_accessed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Form Instance Qr Code Image

Get QR code image for a form instance directly (PNG).

Returns 404 if no QR code exists for this instance.

Authorizations:
HTTPBearer
path Parameters
instance_id
required
string (Instance Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

reports

Report Generation

Generate and manage construction project reports.

Features:

  • Create reports from templates
  • AI-assisted report generation
  • Export reports in multiple formats
  • Schedule automated report generation

Create Report

Create a new report.

Args:

report: Report data to create
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Created report

Raises:

HTTPException: If project not found or user not authorized
Authorizations:
HTTPBearer
Request Body schema: application/json
required
title
required
string (Title)

Report title

project_id
required
string (Project Id)

Associated project ID

content
required
string (Content)

Report content

category
required
string (ReportCategory)
Enum: "Environmental" "Risk" "Construction" "Progress" "Financial" "Quality" "Safety" "Other"

Report category

format
required
string (ReportFormat)
Enum: "Text" "Table" "Combined"

Report format

Array of objects (Sharing)

Sharing permissions

tags
Array of strings (Tags)

Report tags

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "project_id": "string",
  • "content": "string",
  • "category": "Environmental",
  • "format": "Text",
  • "sharing": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "project_id": "string",
  • "project_name": "string",
  • "content": "string",
  • "category": "Environmental",
  • "format": "Text",
  • "created_by": "string",
  • "created_by_name": "string",
  • "sharing": [
    ],
  • "tags": [
    ],
  • "organization_id": "string",
  • "is_deleted": true,
  • "version": 0,
  • "history": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Reports

Get reports with optional filtering and pagination.

Args:

project_id: Optional project ID filter
category: Optional category filter
report_format: Optional format filter
tags: Optional tags filter (comma-separated)
created_by: Optional creator filter
search: Optional text search across title/content/tags
content_keywords: Optional comma-separated keywords to match against content
page: Page number (1-based)
size: Number of items per page
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Paginated response containing reports

Raises:

HTTPException: If database operation fails
Authorizations:
HTTPBearer
query Parameters
Project Id (string) or Project Id (null) (Project Id)

Filter by project ID

ReportCategory (string) or Category (null) (Category)

Filter by category

ReportFormat (string) or Report Format (null) (Report Format)

Filter by format

Tags (string) or Tags (null) (Tags)

Filter by tags (comma-separated)

Created By (string) or Created By (null) (Created By)

Filter by creator user ID

Search (string) or Search (null) (Search)

Text search applied to title, content, and tags

Content Keywords (string) or Content Keywords (null) (Content Keywords)

Comma-separated keywords to match inside content for category-style discovery

page
integer (Page) >= 1
Default: 1

Page number

size
integer (Size) [ 1 .. 100 ]
Default: 10

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Get Reports Batch

Fetch multiple reports in a single request.

Args:

request: Batch request containing list of report IDs
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Batch response containing fetched reports and not found IDs

Raises:

HTTPException: If database operation fails
Authorizations:
HTTPBearer
Request Body schema: application/json
required
report_ids
Array of strings (Report Ids)

List of report IDs to fetch

Responses

Request samples

Content type
application/json
{
  • "report_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "reports": [
    ],
  • "not_found": [
    ]
}

Get Report Categories

Get available report categories.

Returns

List of available report categories
Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get Report Formats

Get available report formats.

Returns

List of available report formats
Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get Report

Get a specific report with associated comments.

Args:

report_id: ID of report to retrieve
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Report data with comments

Raises:

HTTPException: If report not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
report_id
required
string (Report Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "project_id": "string",
  • "project_name": "string",
  • "content": "string",
  • "category": "Environmental",
  • "format": "Text",
  • "created_by": "string",
  • "created_by_name": "string",
  • "sharing": [
    ],
  • "tags": [
    ],
  • "organization_id": "string",
  • "is_deleted": true,
  • "version": 0,
  • "history": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "comments": [
    ],
  • "created_by_user": {
    }
}

Update Report

Update a report.

Args:

report_id: ID of report to update
report_update: Report update data
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Updated report

Raises:

HTTPException: If report not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
report_id
required
string (Report Id)
Request Body schema: application/json
required
Title (string) or Title (null) (Title)

Report title

Content (string) or Content (null) (Content)

Report content

ReportCategory (string) or null

Report category

ReportFormat (string) or null

Report format

Array of Sharing (objects) or Sharing (null) (Sharing)

Sharing permissions

Array of Tags (strings) or Tags (null) (Tags)

Report tags

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "content": "string",
  • "category": "Environmental",
  • "format": "Text",
  • "sharing": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "project_id": "string",
  • "project_name": "string",
  • "content": "string",
  • "category": "Environmental",
  • "format": "Text",
  • "created_by": "string",
  • "created_by_name": "string",
  • "sharing": [
    ],
  • "tags": [
    ],
  • "organization_id": "string",
  • "is_deleted": true,
  • "version": 0,
  • "history": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Report

Delete a report (soft delete).

Args:

report_id: ID of report to delete
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Success message

Raises:

HTTPException: If report not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
report_id
required
string (Report Id)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Update Report Sharing

Update report sharing permissions.

Args:

report_id: ID of report to update sharing for
sharing: New sharing permissions
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Success message

Raises:

HTTPException: If report not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
report_id
required
string (Report Id)
Request Body schema: application/json
required
Array
user_id
required
string (User Id)

User ID

user_name
required
string (User Name)

User name

role
required
string (ShareRole)
Enum: "Owner" "Editor" "Viewer"

Access role

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Get Report History

Get report change history.

Args:

report_id: ID of report to get history for
db: MongoDB client instance
current_user: Current authenticated user
page: Page number (1-based)
size: Number of items per page

Returns:

Paginated history entries

Raises:

HTTPException: If report not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
report_id
required
string (Report Id)
query Parameters
page
integer (Page) >= 1
Default: 1

Page number

size
integer (Size) [ 1 .. 100 ]
Default: 10

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

Get Report Versions

Get previous versions of a report.

Args:

report_id: ID of report to get versions for
version: Optional specific version number to retrieve
db: MongoDB client instance
current_user: Current authenticated user
page: Page number (1-based)
size: Number of items per page

Returns:

Paginated previous versions, each containing version number and report data.
If version parameter is provided, returns only that version if it exists.

Raises:

HTTPException: If report not found, user not authorized, or version not found
Authorizations:
HTTPBearer
path Parameters
report_id
required
string (Report Id)
query Parameters
Version (integer) or Version (null) (Version)

Optional specific version number to retrieve

page
integer (Page) >= 1
Default: 1

Page number

size
integer (Size) [ 1 .. 100 ]
Default: 10

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "has_more": true,
  • "total_pages": 0
}

search

Search & Discovery

Search across all project content including documents, tasks, and forms.

Features:

  • Full-text search with relevance ranking
  • Filter by document type, date, author, and more
  • Semantic search using AI embeddings
  • Search within document content

tasks

Task Management

Create, assign, and track tasks within construction projects.

Features:

  • Create tasks with titles, descriptions, and due dates
  • Assign tasks to team members
  • Track task status and progress
  • Link tasks to documents, forms, and other resources
  • Set priorities and dependencies

List Tasks

List tasks for a project with optional filtering.

Args:

project_id: Project ID
status: Filter by task status
assigned_to: Filter by assigned user ID
current_user: Current authenticated user

Returns:

List of tasks matching the criteria

Raises:

HTTPException: If project not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
query Parameters
Status (string) or Status (null) (Status)
Assigned To (string) or Assigned To (null) (Assigned To)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Task

Create a new task for a project.

Args:

project_id: Project ID
task: Task data
current_user: Current authenticated user
db: Database connection (MongoDB or AsyncIOMotorClient)

Returns:

Created task data

Raises:

HTTPException: If project not found
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
name
required
string (Name)

Name of the task

Description (string) or Description (null) (Description)

Task description

assignment_type
string (AssignmentType)
Default: "user"
Enum: "user" "agent_task"

Type of assignment: user or agent_task

Assigned To (string) or Assigned To (null) (Assigned To)

ID of the assigned user (can be string or PyObjectId)

Assigned Agent Id (string) or Assigned Agent Id (null) (Assigned Agent Id)

Agent ID if assignment_type=AGENT_TASK

Assigned Agent Task Id (string) or Assigned Agent Task Id (null) (Assigned Agent Task Id)

Agent task_id if assignment_type=AGENT_TASK

Agent Task Inputs (object) or Agent Task Inputs (null) (Agent Task Inputs)

Input parameters for the agent task

status
string (Status)
Default: "pending"

Task status

priority
string (TaskPriority)
Default: "medium"
Enum: "low" "medium" "high"

Task priority

Due Date (string) or Due Date (null) (Due Date)

Task due date

Estimated Hours (number) or Estimated Hours (null) (Estimated Hours)

Estimated hours to complete

Actual Hours (number) or Actual Hours (null) (Actual Hours)

Actual hours spent

Completion Percentage (number) or Completion Percentage (null) (Completion Percentage)

Task completion percentage

tags
Array of strings (Tags)

Task tags

dependencies
Array of strings (Dependencies)

IDs of tasks this task depends on

Related Object Id (string) or Related Object Id (null) (Related Object Id)

ID of the related object (e.g., document) this task is associated with

Related Object Type (string) or Related Object Type (null) (Related Object Type)

Type of the related object (e.g., 'document', 'workspace_item')

Project Id (string) or Project Id (null) (Project Id)

ID of the project this task belongs to

Created By (string) or Created By (null) (Created By)

ID of the user creating the task

Closed Reason (string) or Closed Reason (null) (Closed Reason)

Human-readable reason why the task was automatically closed

TaskClosureReason (string) or null

Machine-readable reason code for automatic task closure

TaskSchedule (object) or null

Scheduling configuration for recurring or one-time execution

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "assignment_type": "user",
  • "assigned_to": "string",
  • "assigned_agent_id": "string",
  • "assigned_agent_task_id": "string",
  • "agent_task_inputs": { },
  • "status": "pending",
  • "priority": "low",
  • "due_date": "2019-08-24T14:15:22Z",
  • "estimated_hours": 0,
  • "actual_hours": 0,
  • "completion_percentage": 0,
  • "tags": [
    ],
  • "dependencies": [
    ],
  • "related_object_id": "string",
  • "related_object_type": "string",
  • "project_id": "string",
  • "created_by": "string",
  • "closed_reason": "string",
  • "closed_reason_code": "document_revised",
  • "schedule": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "created_at": "2024-01-01T00:00:00",
  • "created_by": "507f1f77bcf86cd799439013",
  • "description": "An example task",
  • "name": "Example Task",
  • "priority": "medium",
  • "project_id": "507f1f77bcf86cd799439012",
  • "related_object_id": "507f1f77bcf86cd799439014",
  • "related_object_type": "document",
  • "status": "pending",
  • "updated_at": "2024-01-01T00:00:00"
}

Get Task

Get task by ID with associated comments and user information.

Args:

task_id: Task ID
current_user: Current authenticated user

Returns:

Task data with associated comments and user information

Raises:

HTTPException: If task not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
task_id
required
string (Task Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "assigned_user": {
    },
  • "comments": [
    ],
  • "created_at": "2024-01-01T00:00:00",
  • "created_by": "507f1f77bcf86cd799439013",
  • "created_by_user": {
    },
  • "description": "An example task",
  • "name": "Example Task",
  • "priority": "medium",
  • "project_id": "507f1f77bcf86cd799439012",
  • "related_object_id": "507f1f77bcf86cd799439014",
  • "related_object_type": "document",
  • "status": "pending",
  • "updated_at": "2024-01-01T00:00:00"
}

Update Task

Update a task.

Args:

task_id: Task ID
updates: Task updates
current_user: Current authenticated user

Returns:

Updated task data

Raises:

HTTPException: If user not authorized or task not found
Authorizations:
HTTPBearer
path Parameters
task_id
required
string (Task Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
AssignmentType (string) or null
Assigned To (string) or Assigned To (null) (Assigned To)
Assigned Agent Id (string) or Assigned Agent Id (null) (Assigned Agent Id)
Assigned Agent Task Id (string) or Assigned Agent Task Id (null) (Assigned Agent Task Id)
Agent Task Inputs (object) or Agent Task Inputs (null) (Agent Task Inputs)
Status (string) or Status (null) (Status)
TaskPriority (string) or null
Due Date (string) or Due Date (null) (Due Date)
Estimated Hours (number) or Estimated Hours (null) (Estimated Hours)
Actual Hours (number) or Actual Hours (null) (Actual Hours)
Completion Percentage (number) or Completion Percentage (null) (Completion Percentage)
Array of Tags (strings) or Tags (null) (Tags)
Array of Dependencies (strings) or Dependencies (null) (Dependencies)
Related Object Id (string) or Related Object Id (null) (Related Object Id)
Related Object Type (string) or Related Object Type (null) (Related Object Type)
Updated By (string) or Updated By (null) (Updated By)
Closed Reason (string) or Closed Reason (null) (Closed Reason)
TaskClosureReason (string) or null
TaskSchedule (object) or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "assignment_type": "user",
  • "assigned_to": "string",
  • "assigned_agent_id": "string",
  • "assigned_agent_task_id": "string",
  • "agent_task_inputs": { },
  • "status": "string",
  • "priority": "low",
  • "due_date": "2019-08-24T14:15:22Z",
  • "estimated_hours": 0,
  • "actual_hours": 0,
  • "completion_percentage": 0,
  • "tags": [
    ],
  • "dependencies": [
    ],
  • "related_object_id": "string",
  • "related_object_type": "string",
  • "updated_by": "string",
  • "closed_reason": "string",
  • "closed_reason_code": "document_revised",
  • "schedule": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "507f1f77bcf86cd799439011",
  • "created_at": "2024-01-01T00:00:00",
  • "created_by": "507f1f77bcf86cd799439013",
  • "description": "An example task",
  • "name": "Example Task",
  • "priority": "medium",
  • "project_id": "507f1f77bcf86cd799439012",
  • "related_object_id": "507f1f77bcf86cd799439014",
  • "related_object_type": "document",
  • "status": "pending",
  • "updated_at": "2024-01-01T00:00:00"
}

Delete Task

Delete a task.

Args:

task_id: Task ID
current_user: Current authenticated user
db: Database connection (MongoDB or AsyncIOMotorClient)

Returns:

Success message

Raises:

HTTPException: If task not found or user not authorized
Authorizations:
HTTPBearer
path Parameters
task_id
required
string (Task Id)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

virtual-documents

Virtual Documents

Manage virtual document templates and instances.

Features:

  • Create virtual document templates
  • Generate virtual documents from templates
  • Manage virtual document lifecycle

Pdf Renderer Status

Return diagnostic information about the PDF renderer.

This endpoint helps diagnose WeasyPrint availability issues. No authentication required for debugging purposes.

Responses

Response samples

Content type
application/json
{ }

Create Template

Create a new document template.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
template_id
required
string (Template Id)

Unique template slug identifier

template_name
required
string (Template Name)
template_type
required
string (DocumentTemplateType)
Enum: "health_safety_plan" "method_statement" "risk_assessment" "construction_plan" "quality_plan" "environmental_plan" "inspection_report" "compliance_report" "project_report" "project_document" "general_report" "general_document"

Supported virtual document template types.

scope
string (TemplateScope-Input)
Default: "org"
Enum: "app" "org" "project"

Template visibility scope: 'app' for app-wide system templates, 'org' for organization-wide (default), 'project' for project-specific.

version
required
string (Version)

Semantic version string, e.g. 1.0.0

major_version
required
integer (Major Version)
minor_version
required
integer (Minor Version)
patch_version
required
integer (Patch Version)
description
string (Description)
Default: ""
author_user_id
string (Author User Id)
Default: ""

Author user ID (optional - will be set from authenticated user if empty)

Organization Id (string) or Organization Id (null) (Organization Id)

Organization that owns this template (null for app-scoped templates)

project_ids
Array of strings (Project Ids)
Requires License Feature (string) or Requires License Feature (null) (Requires License Feature)
object (Custom Fields)

Template-specific custom values

object (Custom Field Definitions)

Schema definitions for template custom fields

UserInputSchema (object) or null

Declarative schema for collecting per-template user inputs. When present, the frontend can render fields without hardcoding.

Array of objects (Sections)
Array of objects (Data Bindings)
Array of objects (Conditional Sections)
Array of objects (Computed Fields)
Array of objects (Validation Rules)
output_format
string (OutputFormat)
Default: "html"
Enum: "html" "markdown" "json"

Supported rendering formats.

PDFSettings (object) or null
regulatory_references
Array of strings (Regulatory References)
Array of objects (Required Approvals)
retention_period_days
integer (Retention Period Days)
Default: 2555
status
string (TemplateStatus)
Default: "draft"
Enum: "draft" "review" "approved" "published" "archived"

Lifecycle status for document templates.

Published At (string) or Published At (null) (Published At)
is_active
boolean (Is Active)
Default: true
created_at
string <date-time> (Created At)
updated_at
string <date-time> (Updated At)
Estimated Iu (number) or Estimated Iu (null) (Estimated Iu)

Estimated Intelligence Units (IU) cost for generating a document from this template. Based on section count: up to 4 sections = 1 IU, +1 IU per 2 additional sections.

Iu Pricing Note (string) or Iu Pricing Note (null) (Iu Pricing Note)

Human-readable explanation of the IU pricing for this template. Example: '1 IU (4 sections)' or '3 IU (8 sections)'.

Default Source Template Id (string) or Default Source Template Id (null) (Default Source Template Id)

Reference to the original template when cloned from defaults.

Default Snapshot Id (string) or Default Snapshot Id (null) (Default Snapshot Id)

Project defaults identifier if created during defaults application.

RevisionSummaryConfig (object) or null

Optional configuration for persisting revision difference summaries.

Responses

Request samples

Content type
application/json
{
  • "template_id": "string",
  • "template_name": "string",
  • "template_type": "health_safety_plan",
  • "scope": "app",
  • "version": "string",
  • "major_version": 0,
  • "minor_version": 0,
  • "patch_version": 0,
  • "description": "",
  • "author_user_id": "",
  • "organization_id": "string",
  • "project_ids": [
    ],
  • "requires_license_feature": "string",
  • "custom_fields": { },
  • "custom_field_definitions": {
    },
  • "user_input_schema": {
    },
  • "sections": [
    ],
  • "data_bindings": [
    ],
  • "conditional_sections": [
    ],
  • "computed_fields": [
    ],
  • "validation_rules": [
    ],
  • "output_format": "html",
  • "pdf_settings": {
    },
  • "regulatory_references": [
    ],
  • "required_approvals": [
    ],
  • "retention_period_days": 2555,
  • "status": "draft",
  • "published_at": "2019-08-24T14:15:22Z",
  • "is_active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "estimated_iu": 0,
  • "iu_pricing_note": "string",
  • "default_source_template_id": "string",
  • "default_snapshot_id": "string",
  • "revision_summary_config": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "661f7d8a7a7b5d0012fa0a12",
  • "template_id": "health-safety-plan",
  • "template_name": "Construction Phase Health & Safety Plan",
  • "template_type": "health_safety_plan",
  • "version": "1.0.0"
}

List Templates

List available templates with optional filters.

By default includes app-scoped templates along with organization templates.

Authorizations:
HTTPBearer
query Parameters
Organization Id (string) or Organization Id (null) (Organization Id)
DocumentTemplateType (string) or Template Type (null) (Template Type)
TemplateStatus (string) or Status (null) (Status)
TemplateScope (string) or Scope (null) (Scope)

Filter by scope: 'app' for app-wide, 'org' for organization, 'project' for project-specific.

include_app_templates
boolean (Include App Templates)
Default: true

Include app-wide system templates in results (default: true).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Template

Retrieve a single template by ID.

Access is allowed if:

  • Template is app-scoped (available to all users)
  • Template belongs to the user's organization
Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "661f7d8a7a7b5d0012fa0a12",
  • "template_id": "health-safety-plan",
  • "template_name": "Construction Phase Health & Safety Plan",
  • "template_type": "health_safety_plan",
  • "version": "1.0.0"
}

Update Template

Update existing template metadata.

Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)
query Parameters
create_new_version
boolean (Create New Version)
Default: false

Create a new version instead of updating in place

Request Body schema: application/json
required
Template Name (string) or Template Name (null) (Template Name)
DocumentTemplateType (string) or null
TemplateScope (string) or null
Description (string) or Description (null) (Description)
Custom Fields (object) or Custom Fields (null) (Custom Fields)
Custom Field Definitions (object) or Custom Field Definitions (null) (Custom Field Definitions)
Array of Sections (objects) or Sections (null) (Sections)
Array of Data Bindings (objects) or Data Bindings (null) (Data Bindings)
Array of Conditional Sections (objects) or Conditional Sections (null) (Conditional Sections)
Array of Computed Fields (objects) or Computed Fields (null) (Computed Fields)
Array of Validation Rules (objects) or Validation Rules (null) (Validation Rules)
Array of Required Approvals (objects) or Required Approvals (null) (Required Approvals)
Array of Regulatory References (strings) or Regulatory References (null) (Regulatory References)
Array of Project Ids (strings) or Project Ids (null) (Project Ids)
Requires License Feature (string) or Requires License Feature (null) (Requires License Feature)
UserInputSchema (object) or null
TemplateStatus (string) or null
Published At (string) or Published At (null) (Published At)
Is Active (boolean) or Is Active (null) (Is Active)
PDFSettings (object) or null
Retention Period Days (integer) or Retention Period Days (null) (Retention Period Days)
RevisionSummaryConfig (object) or null

Responses

Request samples

Content type
application/json
{
  • "template_name": "string",
  • "template_type": "health_safety_plan",
  • "scope": "app",
  • "description": "string",
  • "custom_fields": { },
  • "custom_field_definitions": {
    },
  • "sections": [
    ],
  • "data_bindings": [
    ],
  • "conditional_sections": [
    ],
  • "computed_fields": [
    ],
  • "validation_rules": [
    ],
  • "required_approvals": [
    ],
  • "regulatory_references": [
    ],
  • "project_ids": [
    ],
  • "requires_license_feature": "string",
  • "user_input_schema": {
    },
  • "status": "draft",
  • "published_at": "2019-08-24T14:15:22Z",
  • "is_active": true,
  • "pdf_settings": {
    },
  • "retention_period_days": 0,
  • "revision_summary_config": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "661f7d8a7a7b5d0012fa0a12",
  • "template_id": "health-safety-plan",
  • "template_name": "Construction Phase Health & Safety Plan",
  • "template_type": "health_safety_plan",
  • "version": "1.0.0"
}

Get Template Placeholders

Get all document placeholders defined in a template.

Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Template Defaults

Get per-project defaults for a template.

Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)
query Parameters
project_id
required
string (Project Id)

Project ID for which to fetch defaults

Responses

Response samples

Content type
application/json
{
  • "project_id": "string",
  • "template_id": "string",
  • "defaults": { }
}

Upsert Template Defaults

Create or update per-project defaults for a template.

Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)
Request Body schema: application/json
required
project_id
required
string (Project Id)
template_id
required
string (Template Id)
object (Defaults)

Responses

Request samples

Content type
application/json
{
  • "project_id": "string",
  • "template_id": "string",
  • "defaults": { }
}

Response samples

Content type
application/json
{
  • "project_id": "string",
  • "template_id": "string",
  • "defaults": { }
}

Validate Document Reference

Validate that a document reference is valid and accessible.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
document_id
required
string (Document Id)
reference_type
required
string (Reference Type)
Array of Pages (integers) or Pages (null) (Pages)

Responses

Request samples

Content type
application/json
{
  • "document_id": "string",
  • "reference_type": "string",
  • "pages": [
    ]
}

Response samples

Content type
application/json
{ }

Generate Revision Summary

Return a concise summary of the differences between the latest revisions.

Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)
Request Body schema: application/json
required
project_id
required
string (Project Id)

Project ID that owns the template document

Document Id (string) or Document Id (null) (Document Id)

Optional explicit document to compare; defaults to the latest version

max_changes
integer (Max Changes) [ 1 .. 50 ]
Default: 12

Limit the number of change entries shared with the summarizer

Responses

Request samples

Content type
application/json
{
  • "project_id": "string",
  • "document_id": "string",
  • "max_changes": 12
}

Response samples

Content type
application/json
{
  • "template_id": "string",
  • "project_id": "string",
  • "summary": "string",
  • "agent_summary": "string",
  • "current_document_id": "string",
  • "previous_document_id": "string",
  • "current_version_number": 0,
  • "previous_version_number": 0,
  • "change_count": 0,
  • "changes": [
    ]
}

Generate Document

Generate a virtual document from template and project data.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
template_id
required
string (Template Id)
project_id
required
string (Project Id)
Title (string) or Title (null) (Title)

Custom title for the generated document (overrides template default)

object (User Inputs)
Default: {}
Array of objects (Document References)

References to documents to insert into the virtual document

Responses

Request samples

Content type
application/json
{
  • "template_id": "string",
  • "project_id": "string",
  • "title": "string",
  • "user_inputs": { },
  • "document_references": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "document_id": "string",
  • "template_id": "string",
  • "template_version": "string",
  • "project_id": "string",
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "title": "string",
  • "document_type": "health_safety_plan",
  • "generated_at": "2019-08-24T14:15:22Z",
  • "generation_trigger": "manual",
  • "generation_duration_ms": 0,
  • "content": "string",
  • "content_r2_key": "string",
  • "content_format": "html",
  • "content_hash": "string",
  • "content_size_bytes": 0,
  • "data_snapshot": { },
  • "data_snapshot_r2_key": "string",
  • "data_snapshot_hash": "string",
  • "data_snapshot_size_bytes": 0,
  • "data_sources_used": [
    ],
  • "version_number": 1,
  • "is_current": true,
  • "supersedes": "string",
  • "status": "draft",
  • "validation_results": [
    ],
  • "is_valid": true,
  • "approval_status": "pending",
  • "approvals": [
    ],
  • "pdf_exports": [
    ],
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "invalidation_reason": "string",
  • "changes_from_previous": [
    ],
  • "agentcon_document_id": "string",
  • "metadata": { },
  • "document_references": [
    ],
  • "revision_summary": "string"
}

Get Virtual Document

Retrieve a generated virtual document.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
query Parameters
include_data_snapshot
boolean (Include Data Snapshot)
Default: false

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "document_id": "string",
  • "template_id": "string",
  • "template_version": "string",
  • "project_id": "string",
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "title": "string",
  • "document_type": "health_safety_plan",
  • "generated_at": "2019-08-24T14:15:22Z",
  • "generation_trigger": "manual",
  • "generation_duration_ms": 0,
  • "content": "string",
  • "content_r2_key": "string",
  • "content_format": "html",
  • "content_hash": "string",
  • "content_size_bytes": 0,
  • "data_snapshot": { },
  • "data_snapshot_r2_key": "string",
  • "data_snapshot_hash": "string",
  • "data_snapshot_size_bytes": 0,
  • "data_sources_used": [
    ],
  • "version_number": 1,
  • "is_current": true,
  • "supersedes": "string",
  • "status": "draft",
  • "validation_results": [
    ],
  • "is_valid": true,
  • "approval_status": "pending",
  • "approvals": [
    ],
  • "pdf_exports": [
    ],
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "invalidation_reason": "string",
  • "changes_from_previous": [
    ],
  • "agentcon_document_id": "string",
  • "metadata": { },
  • "document_references": [
    ],
  • "revision_summary": "string"
}

Update Virtual Document

Update a virtual document in place or create a new version.

  • If create_new_version is False: only metadata/title/status/approval_status may be updated on the existing record.
  • If create_new_version is True: a new document version is generated using the original template and project context. Optional title/metadata/status/approval_status are applied to the newly generated document. Optional user_inputs and document_references influence regeneration.
Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
query Parameters
create_new_version
boolean (Create New Version)
Default: false

Create a new document version based on updates

Request Body schema: application/json
required
Title (string) or Title (null) (Title)
Metadata (object) or Metadata (null) (Metadata)
VirtualDocumentStatus (string) or null
ApprovalStatus (string) or null
Content (string) or Content (null) (Content)
OutputFormat (string) or null
User Inputs (object) or User Inputs (null) (User Inputs)
Array of Document References (objects) or Document References (null) (Document References)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "metadata": { },
  • "status": "draft",
  • "approval_status": "pending",
  • "content": "string",
  • "content_format": "html",
  • "user_inputs": { },
  • "document_references": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "document_id": "string",
  • "template_id": "string",
  • "template_version": "string",
  • "project_id": "string",
  • "organization_id": "string",
  • "created_by_user_id": "string",
  • "title": "string",
  • "document_type": "health_safety_plan",
  • "generated_at": "2019-08-24T14:15:22Z",
  • "generation_trigger": "manual",
  • "generation_duration_ms": 0,
  • "content": "string",
  • "content_r2_key": "string",
  • "content_format": "html",
  • "content_hash": "string",
  • "content_size_bytes": 0,
  • "data_snapshot": { },
  • "data_snapshot_r2_key": "string",
  • "data_snapshot_hash": "string",
  • "data_snapshot_size_bytes": 0,
  • "data_sources_used": [
    ],
  • "version_number": 1,
  • "is_current": true,
  • "supersedes": "string",
  • "status": "draft",
  • "validation_results": [
    ],
  • "is_valid": true,
  • "approval_status": "pending",
  • "approvals": [
    ],
  • "pdf_exports": [
    ],
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_until": "2019-08-24T14:15:22Z",
  • "invalidation_reason": "string",
  • "changes_from_previous": [
    ],
  • "agentcon_document_id": "string",
  • "metadata": { },
  • "document_references": [
    ],
  • "revision_summary": "string"
}

List Virtual Documents For Project

List virtual documents for a given project.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
query Parameters
DocumentTemplateType (string) or Template Type (null) (Template Type)
current_only
boolean (Current Only)
Default: true

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Document Versions

Return version history for a virtual document.

The group is inferred from the given document's template_id, project_id, and title.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
query Parameters
limit
integer (Limit) [ 1 .. 100 ]
Default: 10
sort
string (Sort)
Default: "-version_number"

Sort by field, prefix '-' for desc

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

List Document Versions Via Query

Fetch versions via query parameter document_id.

Authorizations:
HTTPBearer
query Parameters
document_id
required
string (Document Id)

Anchor document_id to list versions for

limit
integer (Limit) [ 1 .. 100 ]
Default: 10
sort
string (Sort)
Default: "-version_number"

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

Export Document Pdf

Render a virtual document as a PDF and store it in R2.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
Request Body schema: application/json
required
purpose
string (Purpose) <= 200 characters
Default: "manual_export"
upload_to_agentcon
boolean (Upload To Agentcon)
Default: false

If true, upload the resulting PDF to the Agent-Con document service.

Filename (string) or Filename (null) (Filename)

Optional filename to use when storing or downloading the PDF.

object (Agentcon Metadata)

Additional metadata to send when uploading to Agent-Con.

Responses

Request samples

Content type
application/json
{
  • "purpose": "manual_export",
  • "upload_to_agentcon": false,
  • "filename": "string",
  • "agentcon_metadata": { }
}

Response samples

Content type
application/json
{
  • "export": {
    },
  • "download_url": "string",
  • "agentcon_document": { }
}

Regenerate Document

Queue a manual regeneration job for an existing document.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
{ }