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

connector-catalogue

connector-catalogue endpoints

List Blueprints

List connector blueprints.

Returns active blueprints by default. Pass include_inactive=true to include archived blueprints in the result.

Authorizations:
HTTPBearer
query Parameters
include_inactive
boolean (Include Inactive)
Default: false

Responses

Response samples

Content type
application/json
[]

List Blueprints

List connector blueprints.

Returns active blueprints by default. Pass include_inactive=true to include archived blueprints in the result.

Authorizations:
HTTPBearer
query Parameters
include_inactive
boolean (Include Inactive)
Default: false

Responses

Response samples

Content type
application/json
[]

Create Blueprint

Create a new connector blueprint (write-restricted).

Authorizations:
HTTPBearer
Request Body schema: application/json
required
connector_id
required
string (Connector Id)

Unique slug for the blueprint, e.g. 'smartwaste'

name
required
string (Name)

Human-readable connector name

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

Short marketing line shown under the name in the gallery

Icon (string) or Icon (null) (Icon)

Icon identifier or URL

tags
Array of strings (Tags)
category
required
string (Category)

Catalogue category, e.g. 'waste-management'

required
object (ConnectorVendor)

Vendor metadata

system_type
string (System Type)
Default: "rest_api"

Underlying transport, mirrors ExternalSystemType

base_url
required
string (Base Url)

Base URL for upstream API calls

required
object (ConnectorAuthentication)

Authentication contract for a connector blueprint.

Array of objects (Actions)
ConnectorHealthCheck (object) or null
Rate Limit Per Minute (integer) or Rate Limit Per Minute (null) (Rate Limit Per Minute)

Token-bucket rate limit applied per (org, connector_slug)

timeout_seconds
integer (Timeout Seconds) [ 1 .. 300 ]
Default: 30
retry_attempts
integer (Retry Attempts) [ 0 .. 10 ]
Default: 3
version
integer (Version) >= 1
Default: 1
active
boolean (Active)
Default: true
object (Metadata)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "connector_id": "string",
  • "name": "string",
  • "description": "string",
  • "tagline": "string",
  • "icon": "string",
  • "tags": [
    ],
  • "category": "string",
  • "vendor": {
    },
  • "system_type": "rest_api",
  • "base_url": "string",
  • "authentication": {
    },
  • "actions": [
    ],
  • "health_check": {
    },
  • "rate_limit_per_minute": 1,
  • "timeout_seconds": 30,
  • "retry_attempts": 3,
  • "version": 1,
  • "active": true,
  • "metadata": { }
}

Response samples

Content type
application/json
{}

Create Blueprint

Create a new connector blueprint (write-restricted).

Authorizations:
HTTPBearer
Request Body schema: application/json
required
connector_id
required
string (Connector Id)

Unique slug for the blueprint, e.g. 'smartwaste'

name
required
string (Name)

Human-readable connector name

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

Short marketing line shown under the name in the gallery

Icon (string) or Icon (null) (Icon)

Icon identifier or URL

tags
Array of strings (Tags)
category
required
string (Category)

Catalogue category, e.g. 'waste-management'

required
object (ConnectorVendor)

Vendor metadata

system_type
string (System Type)
Default: "rest_api"

Underlying transport, mirrors ExternalSystemType

base_url
required
string (Base Url)

Base URL for upstream API calls

required
object (ConnectorAuthentication)

Authentication contract for a connector blueprint.

Array of objects (Actions)
ConnectorHealthCheck (object) or null
Rate Limit Per Minute (integer) or Rate Limit Per Minute (null) (Rate Limit Per Minute)

Token-bucket rate limit applied per (org, connector_slug)

timeout_seconds
integer (Timeout Seconds) [ 1 .. 300 ]
Default: 30
retry_attempts
integer (Retry Attempts) [ 0 .. 10 ]
Default: 3
version
integer (Version) >= 1
Default: 1
active
boolean (Active)
Default: true
object (Metadata)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "connector_id": "string",
  • "name": "string",
  • "description": "string",
  • "tagline": "string",
  • "icon": "string",
  • "tags": [
    ],
  • "category": "string",
  • "vendor": {
    },
  • "system_type": "rest_api",
  • "base_url": "string",
  • "authentication": {
    },
  • "actions": [
    ],
  • "health_check": {
    },
  • "rate_limit_per_minute": 1,
  • "timeout_seconds": 30,
  • "retry_attempts": 3,
  • "version": 1,
  • "active": true,
  • "metadata": { }
}

Response samples

Content type
application/json
{}

Get Blueprint

Fetch a single blueprint by connector_id.

Authorizations:
HTTPBearer
path Parameters
connector_id
required
string (Connector Id)

Responses

Response samples

Content type
application/json
{}

Get Blueprint

Fetch a single blueprint by connector_id.

Authorizations:
HTTPBearer
path Parameters
connector_id
required
string (Connector Id)

Responses

Response samples

Content type
application/json
{}

Update Blueprint

Update an existing blueprint (write-restricted).

Authorizations:
HTTPBearer
path Parameters
connector_id
required
string (Connector Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Tagline (string) or Tagline (null) (Tagline)
Icon (string) or Icon (null) (Icon)
Array of Tags (strings) or Tags (null) (Tags)
Category (string) or Category (null) (Category)
ConnectorVendor (object) or null
System Type (string) or System Type (null) (System Type)
Base Url (string) or Base Url (null) (Base Url)
ConnectorAuthentication (object) or null
Array of Actions (objects) or Actions (null) (Actions)
ConnectorHealthCheck (object) or null
Rate Limit Per Minute (integer) or Rate Limit Per Minute (null) (Rate Limit Per Minute)
Timeout Seconds (integer) or Timeout Seconds (null) (Timeout Seconds)
Retry Attempts (integer) or Retry Attempts (null) (Retry Attempts)
Version (integer) or Version (null) (Version)
Active (boolean) or Active (null) (Active)
Metadata (object) or Metadata (null) (Metadata)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tagline": "string",
  • "icon": "string",
  • "tags": [
    ],
  • "category": "string",
  • "vendor": {
    },
  • "system_type": "string",
  • "base_url": "string",
  • "authentication": {
    },
  • "actions": [
    ],
  • "health_check": {
    },
  • "rate_limit_per_minute": 0,
  • "timeout_seconds": 0,
  • "retry_attempts": 0,
  • "version": 0,
  • "active": true,
  • "metadata": { }
}

Response samples

Content type
application/json
{}

Update Blueprint

Update an existing blueprint (write-restricted).

Authorizations:
HTTPBearer
path Parameters
connector_id
required
string (Connector Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Tagline (string) or Tagline (null) (Tagline)
Icon (string) or Icon (null) (Icon)
Array of Tags (strings) or Tags (null) (Tags)
Category (string) or Category (null) (Category)
ConnectorVendor (object) or null
System Type (string) or System Type (null) (System Type)
Base Url (string) or Base Url (null) (Base Url)
ConnectorAuthentication (object) or null
Array of Actions (objects) or Actions (null) (Actions)
ConnectorHealthCheck (object) or null
Rate Limit Per Minute (integer) or Rate Limit Per Minute (null) (Rate Limit Per Minute)
Timeout Seconds (integer) or Timeout Seconds (null) (Timeout Seconds)
Retry Attempts (integer) or Retry Attempts (null) (Retry Attempts)
Version (integer) or Version (null) (Version)
Active (boolean) or Active (null) (Active)
Metadata (object) or Metadata (null) (Metadata)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tagline": "string",
  • "icon": "string",
  • "tags": [
    ],
  • "category": "string",
  • "vendor": {
    },
  • "system_type": "string",
  • "base_url": "string",
  • "authentication": {
    },
  • "actions": [
    ],
  • "health_check": {
    },
  • "rate_limit_per_minute": 0,
  • "timeout_seconds": 0,
  • "retry_attempts": 0,
  • "version": 0,
  • "active": true,
  • "metadata": { }
}

Response samples

Content type
application/json
{}

Get Global Manifest

Return the lightweight gallery feed used by the frontend.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "key": "global",
  • "version": 1,
  • "entries": [
    ],
  • "metadata": { },
  • "published_at": "2019-08-24T14:15:22Z"
}

Get Global Manifest

Return the lightweight gallery feed used by the frontend.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "key": "global",
  • "version": 1,
  • "entries": [
    ],
  • "metadata": { },
  • "published_at": "2019-08-24T14:15:22Z"
}

Create Global Manifest

Create the global catalogue manifest (write-restricted).

Authorizations:
HTTPBearer
Request Body schema: application/json
required
key
string (Key)
Default: "global"

Manifest key (only 'global' is used today)

version
integer (Version) >= 1
Default: 1
Array of objects (Entries)
object (Metadata)
published_at
string <date-time> (Published At)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "key": "global",
  • "version": 1,
  • "entries": [
    ],
  • "metadata": { },
  • "published_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "key": "global",
  • "version": 1,
  • "entries": [
    ],
  • "metadata": { },
  • "published_at": "2019-08-24T14:15:22Z"
}

Create Global Manifest

Create the global catalogue manifest (write-restricted).

Authorizations:
HTTPBearer
Request Body schema: application/json
required
key
string (Key)
Default: "global"

Manifest key (only 'global' is used today)

version
integer (Version) >= 1
Default: 1
Array of objects (Entries)
object (Metadata)
published_at
string <date-time> (Published At)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "key": "global",
  • "version": 1,
  • "entries": [
    ],
  • "metadata": { },
  • "published_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "key": "global",
  • "version": 1,
  • "entries": [
    ],
  • "metadata": { },
  • "published_at": "2019-08-24T14:15:22Z"
}

Update Global Manifest

Update the global catalogue manifest (write-restricted).

Authorizations:
HTTPBearer
Request Body schema: application/json
required
Version (integer) or Version (null) (Version)
Array of Entries (objects) or Entries (null) (Entries)
Metadata (object) or Metadata (null) (Metadata)
Published At (string) or Published At (null) (Published At)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "version": 0,
  • "entries": [
    ],
  • "metadata": { },
  • "published_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "key": "global",
  • "version": 1,
  • "entries": [
    ],
  • "metadata": { },
  • "published_at": "2019-08-24T14:15:22Z"
}

Update Global Manifest

Update the global catalogue manifest (write-restricted).

Authorizations:
HTTPBearer
Request Body schema: application/json
required
Version (integer) or Version (null) (Version)
Array of Entries (objects) or Entries (null) (Entries)
Metadata (object) or Metadata (null) (Metadata)
Published At (string) or Published At (null) (Published At)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "version": 0,
  • "entries": [
    ],
  • "metadata": { },
  • "published_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "key": "global",
  • "version": 1,
  • "entries": [
    ],
  • "metadata": { },
  • "published_at": "2019-08-24T14:15:22Z"
}

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

Viewable Pdf Path (string) or Viewable Pdf Path (null) (Viewable Pdf Path)

R2 path to a viewable PDF rendition of the document. Populated for Word documents (.doc/.docx), which browsers cannot render natively, so the in-app viewer can fetch and display a PDF instead. PDFs are served from r2_path directly and leave this unset.

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

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

Hex digest of the document's raw bytes (SHA-256 by default). Indexed for content-based deduplication and submission-to-document matching (spec §4.2-4.3).

Content Hash Algo (string) or Content Hash Algo (null) (Content Hash Algo)

Algorithm used to compute content_hash (e.g. 'sha256')

DocumentSource (string) or null

How this document entered the system (upload, cde_sync, public_submission, …)

SourceSubmissionRef (object) or null

Back-reference to the public-page submission this document was ingested from. Set only when source == PUBLIC_SUBMISSION.

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

DrawingComparisonStatus (string) or null

Status of automatic drawing comparison for this document. PENDING means the comparison is deferred (e.g. parent still processing) and will be retried; NOT_APPLICABLE means no comparison is expected.

Comparison Status Reason (string) or Comparison Status Reason (null) (Comparison Status Reason)

Human-readable explanation for the current comparison_status.

Page Count (integer) or Page Count (null) (Page Count)

Number of pages detected for this document (PDF page count). None when the page count could not be determined.

Comparison Eligible (boolean) or Comparison Eligible (null) (Comparison Eligible)

Whether this document is eligible for drawing comparison. True for single-page documents, False for multi-page documents, None when eligibility could not be determined (e.g. unknown page count).

ComparisonEligibility (string) or null

Machine-readable reason for the comparison eligibility decision (e.g. eligible, excluded_multipage, unknown_page_count).

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

Document ID of the parent document this is an explicit revision of

removed_in_resubmission
boolean (Removed In Resubmission)
Default: false

Flagged when this document's slot/file was not re-supplied in a later resubmission for the same recipient+page. The document is never auto-deleted; this flag lets the UI surface the gap (spec §4.6).

Removed In Resubmission At (string) or Removed In Resubmission At (null) (Removed In Resubmission At)

When the document was flagged as removed-in-resubmission, if ever

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

is_latest
boolean (Is Latest)
Default: true

Whether this is the latest version

is_deleted
boolean (Is Deleted)
Default: false

Whether the document is deleted

PhotoMetadata (object) or null

EXIF and device metadata for photo documents (location, device, timestamp)

org_extraction_status
string (OrgExtractionStatus)
Default: "pending"
Enum: "pending" "success" "partial" "failed_enrichment" "failed_creation"

Status of organization extraction during document processing

Org Extraction Error (string) or Org Extraction Error (null) (Org Extraction Error)

Human-readable summary of the last org extraction error, if any

Extracted Organization (object) or Extracted Organization (null) (Extracted Organization)

Summary of the organization extracted from this document: {id, name, website_domain} or null.

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

AssigneeUser (object) or null

User who uploaded the document (overridden server-side)

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",
  • "viewable_pdf_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "filename": "string",
  • "r2_path": "string",
  • "file_extension": "string",
  • "file_handling_tier": "RECORD_ONLY",
  • "content_hash": "string",
  • "content_hash_algo": "string",
  • "source": "upload",
  • "source_submission_ref": {
    },
  • "drawing_comparison_id": "string",
  • "comparison_status": "NOT_APPLICABLE",
  • "comparison_status_reason": "string",
  • "page_count": 0,
  • "comparison_eligible": true,
  • "comparison_eligibility_reason": "eligible",
  • "revision_of": "string",
  • "removed_in_resubmission": false,
  • "removed_in_resubmission_at": "2019-08-24T14:15:22Z",
  • "virtual_document_id": "string",
  • "virtual_document_version": 0,
  • "auto_generated": false,
  • "is_latest": true,
  • "is_deleted": false,
  • "photo_metadata": {
    },
  • "org_extraction_status": "pending",
  • "org_extraction_error": "string",
  • "extracted_organization": { },
  • "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": {
    },
  • "org_extraction_status": "pending",
  • "org_extraction_error": "string",
  • "extracted_organization": { },
  • "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",
  • "comparison_status": "NOT_APPLICABLE",
  • "comparison_status_reason": "string",
  • "page_count": 0,
  • "comparison_eligible": true,
  • "comparison_eligibility_reason": "eligible",
  • "revision_of": "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
compact: Exclude large fields (content, version_history) for lighter responses
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)

Organisation 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

compact
boolean (Compact)
Default: false

Return compact response excluding large fields like 'content' and 'version_history'. Useful for listing documents without the full extracted text.

Responses

Response samples

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

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",
  • "viewable_pdf_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "filename": "string",
  • "r2_path": "string",
  • "file_extension": "string",
  • "file_handling_tier": "RECORD_ONLY",
  • "content_hash": "string",
  • "content_hash_algo": "string",
  • "source": "upload",
  • "source_submission_ref": {
    },
  • "drawing_comparison_id": "string",
  • "comparison_status": "NOT_APPLICABLE",
  • "comparison_status_reason": "string",
  • "page_count": 0,
  • "comparison_eligible": true,
  • "comparison_eligibility_reason": "eligible",
  • "revision_of": "string",
  • "removed_in_resubmission": false,
  • "removed_in_resubmission_at": "2019-08-24T14:15:22Z",
  • "virtual_document_id": "string",
  • "virtual_document_version": 0,
  • "auto_generated": false,
  • "is_latest": true,
  • "is_deleted": false,
  • "photo_metadata": {
    },
  • "org_extraction_status": "pending",
  • "org_extraction_error": "string",
  • "extracted_organization": { },
  • "_id": "string",
  • "project_id": "string",
  • "organization_id": "string",
  • "authoring_organization_id": "string",
  • "uploaded_at": "2019-08-24T14:15:22Z",
  • "last_modified": "2019-08-24T14:15:22Z",
  • "task_ids": [
    ],
  • "related_queries": [
    ],
  • "handover_links": [
    ]
}

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": {
    },
  • "org_extraction_status": "pending",
  • "org_extraction_error": "string",
  • "extracted_organization": { },
  • "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",
  • "comparison_status": "NOT_APPLICABLE",
  • "comparison_status_reason": "string",
  • "page_count": 0,
  • "comparison_eligible": true,
  • "comparison_eligibility_reason": "eligible",
  • "revision_of": "string"
}

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"
}

Get Document Revisions

Return the full revision chain for a document, oldest first.

Enumerates every document linked to the requested one through revision_of (in either direction), giving the API/UI a way to list "all revisions of document X" (APP-1212).

Args:

document_id: ID of any document in the chain
db: MongoDB client instance
current_user: Current authenticated user

Returns:

RevisionChainResponse ordered oldest -> newest

Raises:

HTTPException: If the document is not found or access is denied
Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
{
  • "document_id": "string",
  • "count": 0,
  • "revisions": [
    ]
}

Restore Document

Restore (un-delete) a soft-deleted document. Org-admin only (APP-819).

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

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

List handover items that reference this document as evidence

Return the reverse-index entries recording which HandoverItems cite this document.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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
current_user: Current authenticated user

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 View Url

Generate a presigned inline view URL for the in-app multi-page viewer.

Returns a plain presigned GET URL (no Content-Disposition: attachment) so a browser-side PDF renderer can fetch and display the bytes inline:

  • PDFs (and images) are served from the original r2_path.
  • Word documents and PowerPoint decks are served from the viewable_pdf_path PDF rendition produced during processing — browsers cannot render .docx/.pptx natively.

The accurate page_count (derived from the rendered PDF — the slide count for PowerPoint) is returned alongside so the viewer can show a page badge.

Args:

document_id: ID of the document to view
expiration: URL expiration time in seconds
db: MongoDB client instance
current_user: Current authenticated user

Returns:

Dictionary with the inline ``view_url``, ``content_type``,
``page_count`` and ``expires_at``.

Raises:

HTTPException: If the document or a viewable rendition is not found, or
    the caller is not authorised.
Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
query Parameters
expiration
integer (Expiration) [ 300 .. 86400 ]
Default: 3600

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

Responses

Response samples

Content type
application/json
{ }

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",
  • "viewable_pdf_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "filename": "string",
  • "r2_path": "string",
  • "file_extension": "string",
  • "file_handling_tier": "RECORD_ONLY",
  • "content_hash": "string",
  • "content_hash_algo": "string",
  • "source": "upload",
  • "source_submission_ref": {
    },
  • "drawing_comparison_id": "string",
  • "comparison_status": "NOT_APPLICABLE",
  • "comparison_status_reason": "string",
  • "page_count": 0,
  • "comparison_eligible": true,
  • "comparison_eligibility_reason": "eligible",
  • "revision_of": "string",
  • "removed_in_resubmission": false,
  • "removed_in_resubmission_at": "2019-08-24T14:15:22Z",
  • "virtual_document_id": "string",
  • "virtual_document_version": 0,
  • "auto_generated": false,
  • "is_latest": true,
  • "is_deleted": false,
  • "photo_metadata": {
    },
  • "org_extraction_status": "pending",
  • "org_extraction_error": "string",
  • "extracted_organization": { },
  • "_id": "string",
  • "project_id": "string",
  • "organization_id": "string",
  • "authoring_organization_id": "string",
  • "uploaded_at": "2019-08-24T14:15:22Z",
  • "last_modified": "2019-08-24T14:15:22Z",
  • "task_ids": [
    ],
  • "related_queries": [
    ],
  • "handover_links": [
    ]
}

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": {
    },
  • "original_image_url": "string",
  • "comparison_image_url": "string"
}

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

Connector Slug (string) or Connector Slug (null) (Connector Slug)

Optional reference to a ConnectorBlueprint.connector_id. When set, blueprint-derived fields (base_url, system_type, authentication_type, custom_headers) are locked server-side.

Connector Version (integer) or Connector Version (null) (Connector Version)

Version of the linked ConnectorBlueprint when the system was created/updated

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",
  • "connector_slug": "string",
  • "connector_version": 0,
  • "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",
  • "connector_slug": "string",
  • "connector_version": 0,
  • "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

Connector Slug (string) or Connector Slug (null) (Connector Slug)

Optional reference to a ConnectorBlueprint.connector_id. When set, blueprint-derived fields (base_url, system_type, authentication_type, custom_headers) are locked server-side.

Connector Version (integer) or Connector Version (null) (Connector Version)

Version of the linked ConnectorBlueprint when the system was created/updated

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",
  • "connector_slug": "string",
  • "connector_version": 0,
  • "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",
  • "connector_slug": "string",
  • "connector_version": 0,
  • "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)

Organisation 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)

Organisation 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",
  • "connector_slug": "string",
  • "connector_version": 0,
  • "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",
  • "connector_slug": "string",
  • "connector_version": 0,
  • "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
Connector Slug (string) or Connector Slug (null) (Connector Slug)
Connector Version (integer) or Connector Version (null) (Connector Version)
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",
  • "connector_slug": "string",
  • "connector_version": 0,
  • "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",
  • "connector_slug": "string",
  • "connector_version": 0,
  • "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
Connector Slug (string) or Connector Slug (null) (Connector Slug)
Connector Version (integer) or Connector Version (null) (Connector Version)
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",
  • "connector_slug": "string",
  • "connector_version": 0,
  • "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",
  • "connector_slug": "string",
  • "connector_version": 0,
  • "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 Health Check

Run the blueprint's declared health check against the upstream.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
Request Body schema: application/json
Any of
object (Path Params)
object (Query Params)
Body (object) or Body (null) (Body)
Organization Id (string) or Organization Id (null) (Organization Id)

Responses

Request samples

Content type
application/json
Example
{
  • "path_params": {
    },
  • "query_params": { },
  • "body": { },
  • "organization_id": "string"
}

Response samples

Content type
application/json
{ }

Proxy Health Check

Run the blueprint's declared health check against the upstream.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
Request Body schema: application/json
Any of
object (Path Params)
object (Query Params)
Body (object) or Body (null) (Body)
Organization Id (string) or Organization Id (null) (Organization Id)

Responses

Request samples

Content type
application/json
Example
{
  • "path_params": {
    },
  • "query_params": { },
  • "body": { },
  • "organization_id": "string"
}

Response samples

Content type
application/json
{ }

Proxy Geoapify Geocode Deprecated

Backwards-compatible Geoapify geocoding shim.

Prefer POST /external-systems/{system_id}/proxy/{action_slug} once the blueprint is in place. When the system is blueprint-linked this delegates to the generic proxy (action geocode); otherwise it falls back to the historical bespoke flow so existing custom integrations keep working.

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 Deprecated

Backwards-compatible Geoapify geocoding shim.

Prefer POST /external-systems/{system_id}/proxy/{action_slug} once the blueprint is in place. When the system is blueprint-linked this delegates to the generic proxy (action geocode); otherwise it falls back to the historical bespoke flow so existing custom integrations keep working.

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 Action

Forward an action call through the linked connector blueprint.

Resolves system_id to an ExternalSystem, looks up the linked ConnectorBlueprint, validates that action_slug is declared, applies rate limits, and forwards the call upstream with stored credentials.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
action_slug
required
string (Action Slug)
Request Body schema: application/json
Any of
object (Path Params)
object (Query Params)
Body (object) or Body (null) (Body)
Organization Id (string) or Organization Id (null) (Organization Id)

Responses

Request samples

Content type
application/json
Example
{
  • "path_params": {
    },
  • "query_params": { },
  • "body": { },
  • "organization_id": "string"
}

Response samples

Content type
application/json
{ }

Proxy Action

Forward an action call through the linked connector blueprint.

Resolves system_id to an ExternalSystem, looks up the linked ConnectorBlueprint, validates that action_slug is declared, applies rate limits, and forwards the call upstream with stored credentials.

Authorizations:
HTTPBearer
path Parameters
system_id
required
string (System Id)
action_slug
required
string (Action Slug)
Request Body schema: application/json
Any of
object (Path Params)
object (Query Params)
Body (object) or Body (null) (Body)
Organization Id (string) or Organization Id (null) (Organization Id)

Responses

Request samples

Content type
application/json
Example
{
  • "path_params": {
    },
  • "query_params": { },
  • "body": { },
  • "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'.

allowed_instance_types
Array of strings (Allowed Instance Types)
Items Enum: "assigned" "open" "anonymous"

Instance types that can be selected when issuing this form. Omit or pass all three to allow all methods. Exclude 'anonymous' for forms requiring identified recipients.

Issue Via Agent Task Id (string) or Issue Via Agent Task Id (null) (Issue Via Agent Task Id)

Optional agent task_id slug. When set, the front-end's 'Issue' action should run the named agent task instead of calling POST /forms/instances directly. Use this for templates that need server-side hydration before issue.

default_allow_self_service
boolean (Default Allow Self Service)
Default: false

Let supervisors request additional permits themselves from the public link, without a project manager issuing each one. Off by default.

Default Self Service Cap (integer) or Default Self Service Cap (null) (Default Self Service Cap)

How many extra permits a supervisor may request from one permit. Must be 1 or more. Leave empty for no limit. Only applies when self-service is on.

Responses

Request samples

Content type
application/json
{
  • "scope": "app",
  • "project_id": "string",
  • "name": "string",
  • "description": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "sequence_config": {
    },
  • "allowed_instance_types": [
    ],
  • "issue_via_agent_task_id": "string",
  • "default_allow_self_service": false,
  • "default_self_service_cap": 0
}

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",
  • "updated_by_user_id": "string",
  • "archived": false,
  • "is_deleted": true,
  • "latest_version_number": 0,
  • "latest_version_id": "string",
  • "sequence_config": {
    },
  • "allowed_instance_types": [
    ],
  • "issue_via_agent_task_id": "string",
  • "default_allow_self_service": false,
  • "default_self_service_cap": 0,
  • "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)
  • search: Full-text search across template name, description, tags, and category

Templates are returned in order of most recently updated first (or by relevance when searching).

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.

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

Full-text search across template name, description, tags, and category. Results are ranked by relevance.

include_archived
boolean (Include Archived)
Default: false

Include archived templates in results (default: false).

page
integer (Page) >= 1
Default: 1

Page number (1-based).

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

Number of items per page (max 200).

Responses

Response samples

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

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",
  • "updated_by_user_id": "string",
  • "archived": false,
  • "is_deleted": true,
  • "latest_version_number": 0,
  • "latest_version_id": "string",
  • "sequence_config": {
    },
  • "allowed_instance_types": [
    ],
  • "issue_via_agent_task_id": "string",
  • "default_allow_self_service": false,
  • "default_self_service_cap": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a form template

Update a form template's metadata and self-service policy.

Returns 200 with the full, updated template body so the Form Builder can round-trip the saved state (this endpoint does not return 204).

Only the following non-versioned fields can be updated:

  • name: Template display name
  • description: Template description
  • category: Category for organisation
  • tags: Tags for filtering
  • archived: Archive/unarchive the template
  • default_allow_self_service: Allow supervisors to self-issue additional permits
  • default_self_service_cap: Maximum self-issued permits per origin permit (1 or more)

Self-service rules:

  • A cap must be 1 or more; zero or negative values are rejected with 422.
  • Saving with default_allow_self_service: false clears any stale cap.
  • Sending a cap together with default_allow_self_service: false is rejected with 422.

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"],
  "default_allow_self_service": true,
  "default_self_service_cap": 2
}
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.

Archived (boolean) or Archived (null) (Archived)

Set to true to archive (hide from listings) or false to unarchive.

FormSequenceConfig (object) or null

Updated sequence configuration for form references.

Array of Allowed Instance Types (strings) or Allowed Instance Types (null) (Allowed Instance Types)

Updated list of allowed instance types. Replaces existing list entirely.

Issue Via Agent Task Id (string) or Issue Via Agent Task Id (null) (Issue Via Agent Task Id)

Updated agent-task slug used by the front-end's 'Issue' action. Pass an empty string to clear (omit to leave unchanged).

Default Allow Self Service (boolean) or Default Allow Self Service (null) (Default Allow Self Service)

Let supervisors request additional permits themselves from the public link, without a project manager issuing each one. Turn this off to keep issuing manual-only.

Default Self Service Cap (integer) or Default Self Service Cap (null) (Default Self Service Cap)

How many extra permits a supervisor may request from one permit. Must be 1 or more. Leave empty for no limit. Only applies when self-service is on.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "category": "Environmental",
  • "tags": [
    ],
  • "archived": true,
  • "sequence_config": {
    },
  • "allowed_instance_types": [
    ],
  • "issue_via_agent_task_id": "string",
  • "default_allow_self_service": true,
  • "default_self_service_cap": 0
}

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",
  • "updated_by_user_id": "string",
  • "archived": false,
  • "is_deleted": true,
  • "latest_version_number": 0,
  • "latest_version_id": "string",
  • "sequence_config": {
    },
  • "allowed_instance_types": [
    ],
  • "issue_via_agent_task_id": "string",
  • "default_allow_self_service": false,
  • "default_self_service_cap": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List template audit entries

Returns audit log entries for the given template in reverse-chronological order. Currently captures changes to self-service policy fields.

Authorizations:
HTTPBearer
path Parameters
template_id
required
string (Template Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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 SummaryConfigEntry (object))) 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)
Default Allow Self Service (boolean) or Default Allow Self Service (null) (Default Allow Self Service)

Deprecated: use FormTemplate.default_allow_self_service. Kept for one release while the frontend migrates.

Default Self Service Cap (integer) or Default Self Service Cap (null) (Default Self Service Cap)

Deprecated: use FormTemplate.default_self_service_cap. Kept for one release while the frontend migrates.

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": [
    ],
  • "default_allow_self_service": true,
  • "default_self_service_cap": 0
}

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",
  • "default_allow_self_service": true,
  • "default_self_service_cap": 0
}

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 .. 200 ]
Default: 20

Number of items per page (max 200).

Responses

Response samples

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

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",
  • "default_allow_self_service": true,
  • "default_self_service_cap": 0
}

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",
  • "default_allow_self_service": true,
  • "default_self_service_cap": 0
}

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.

Allow Self Service (boolean) or Allow Self Service (null) (Allow Self Service)

Per-instance override letting supervisors self-issue additional sibling permits from the public link. When null, the value is inherited from the template default (then the deprecated version default). Overrides the template default when set.

Self Service Cap (integer) or Self Service Cap (null) (Self Service Cap)

Per-instance cap on how many extra permits can be self-issued from this instance's family. Must be 1 or more. Leave null for no limit. Only applies when allow_self_service resolves to true; ignored (cleared) when it resolves to false.

Run Follow On Agent Task (boolean) or Run Follow On Agent Task (null) (Run Follow On Agent Task)

Per-issue choice for whether the form's follow-on agent on-submit task(s) should run when this instance is submitted. When null, the value is inherited from the project default and then the organisation default. Only meaningful when the form's active version has an AGENT_TASK on-submit task.

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": [
    ],
  • "allow_self_service": true,
  • "self_service_cap": 0,
  • "run_follow_on_agent_task": true
}

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",
  • "current_section_awaiting_user": false,
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "reference": "string",
  • "origin_instance_id": "string",
  • "permit_group_id": "string",
  • "requested_by_email": "string",
  • "allow_self_service": true,
  • "self_service_cap": 0,
  • "run_follow_on_agent_task": true,
  • "summary_values": [
    ],
  • "permissions": {
    },
  • "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).

Permit Group Id (string) or Permit Group Id (null) (Permit Group Id)

Filter by permit_group_id to return all sibling permits in a family.

Requested By Email (string) or Requested By Email (null) (Requested By Email)

Filter by the requester's email. Combine with template_id and project_id to locate a recipient's permit family when permit_group_id is unknown.

Origin Instance Id (string) or Origin Instance Id (null) (Origin Instance Id)

Filter by origin instance ID to return its direct clones.

page
integer (Page) >= 1
Default: 1

Page number (1-based).

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

Number of items per page (max 200).

Responses

Response samples

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

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.

Allow Self Service (boolean) or Allow Self Service (null) (Allow Self Service)

Per-instance override applied to every issued instance, letting supervisors self-issue additional sibling permits from the public link. When null, the value is inherited from the template default (then the deprecated version default).

Self Service Cap (integer) or Self Service Cap (null) (Self Service Cap)

Per-instance cap applied to every issued instance. Must be 1 or more. Leave null for no limit. Only applies when allow_self_service resolves to true.

Run Follow On Agent Task (boolean) or Run Follow On Agent Task (null) (Run Follow On Agent Task)

Per-issue choice applied to every issued instance for whether the form's follow-on agent on-submit task(s) should run. When null, the value is inherited from the project default and then the organisation default.

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": [
    ],
  • "allow_self_service": true,
  • "self_service_cap": 0,
  • "run_follow_on_agent_task": true
}

Response samples

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

List form instances linked to a company or person

List form instances linked to an organisation (company) and/or a person, with a worklist status per instance and a roll-up summary.

Drives the "Forms" tab on the company/person detail surface. Provide organization_id to scope to a company, and/or user_id to narrow to the forms issued to a specific person. At least one must be supplied.

Each instance carries a worklist status:

  • completed: the form has been submitted
  • in_progress: started but not yet submitted
  • overdue: past its due date (or expired) and not submitted
  • not_started: issued but not started and not overdue

The summary rolls these up into total, complete, overdue, in_progress and not_started. Cancelled instances are excluded unless include_cancelled is set.

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

Company (organisation) to list linked forms for.

User Id (string) or User Id (null) (User Id)

Person (recipient user ID) to narrow the linked forms to.

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

Optional project filter.

include_cancelled
boolean (Include Cancelled)
Default: false

Include cancelled instances in the results and summary.

limit
integer (Limit) [ 1 .. 500 ]
Default: 200

Maximum instances to return.

Responses

Response samples

Content type
application/json
{
  • "instances": [
    ],
  • "summary": {
    }
}

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",
  • "current_section_awaiting_user": false,
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "reference": "string",
  • "origin_instance_id": "string",
  • "permit_group_id": "string",
  • "requested_by_email": "string",
  • "allow_self_service": true,
  • "self_service_cap": 0,
  • "run_follow_on_agent_task": true,
  • "summary_values": [
    ],
  • "permissions": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Clone a form instance into a sibling permit

Clone an existing form instance into a fresh sibling instance, inheriting template, pinned version, prefill/locked/hidden fields, workflow config, instructions, project and expiry policy. The clone is linked back to the origin via origin_instance_id and shares a permit_group_id with all other siblings in the family.

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

External requester details for self-serve clones from the public view. Mutually optional with an authenticated session: when the caller is an authenticated user, identity is taken from the session.

Requested By Email (string) or Requested By Email (null) (Requested By Email)

Override for the requester's email. When omitted, it is derived from requester_external or the authenticated user's profile.

Responses

Request samples

Content type
application/json
Example
{
  • "requester_external": {
    },
  • "requested_by_email": "string"
}

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",
  • "current_section_awaiting_user": false,
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "reference": "string",
  • "origin_instance_id": "string",
  • "permit_group_id": "string",
  • "requested_by_email": "string",
  • "allow_self_service": true,
  • "self_service_cap": 0,
  • "run_follow_on_agent_task": true,
  • "summary_values": [
    ],
  • "permissions": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Cancel Instance

Cancel (dismiss) a form instance.

Only instances with status 'issued', 'in_progress' or 'expired' can be cancelled. The status held immediately before cancellation is recorded so the instance can be restored via the reinstate endpoint (Undo). The call is idempotent: cancelling an already-cancelled instance returns it unchanged.

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",
  • "current_section_awaiting_user": false,
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "reference": "string",
  • "origin_instance_id": "string",
  • "permit_group_id": "string",
  • "requested_by_email": "string",
  • "allow_self_service": true,
  • "self_service_cap": 0,
  • "run_follow_on_agent_task": true,
  • "summary_values": [
    ],
  • "permissions": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Reinstate Instance

Reinstate (un-cancel) a previously cancelled form instance.

Backs the Undo affordance on the Forms Dashboard quick-dismiss flow. The instance is restored to the lifecycle state it held before being dismissed (recorded in previous_status; defaulting to 'issued' when unknown). The call is idempotent: reinstating an instance that is not cancelled returns it unchanged, so a duplicate Undo request is harmless.

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",
  • "current_section_awaiting_user": false,
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "reference": "string",
  • "origin_instance_id": "string",
  • "permit_group_id": "string",
  • "requested_by_email": "string",
  • "allow_self_service": true,
  • "self_service_cap": 0,
  • "run_follow_on_agent_task": true,
  • "summary_values": [
    ],
  • "permissions": {
    },
  • "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)
Instance Id (string) or Instance Id (null) (Instance 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)
Template Id (string) or Template Id (null) (Template Id)

Filter by form template ID

page
integer (Page) >= 1
Default: 1
size
integer (Size) [ 1 .. 200 ]
Default: 20

Responses

Response samples

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

List in-progress / partial workflow form instances

List workflow form instances that have not yet been finalized into a submission.

The default Responses listing (GET /submissions) only returns fully-submitted forms, which leaves an audit gap for workflow forms whose state lives in per-section completions (e.g. a permit that has been granted but not closed). This endpoint surfaces those partial instances and includes the latest completion per section so callers can show who signed what, when, with which signature, and link back to the per-section audit trail.

By default, instances with status submitted, cancelled, or expired are excluded. Pass include_expired=true to retain expired instances in the result.

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.

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 internal user the form was issued to.

include_expired
boolean (Include Expired)
Default: false

Include expired instances in the result.

page
integer (Page) >= 1
Default: 1
size
integer (Size) [ 1 .. 200 ]
Default: 20

Responses

Response samples

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

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 .. 200 ]
Default: 20

Responses

Response samples

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

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

SignatureMethod (string) or null

How the signature was produced. Required when signature_data or use_saved_signature is provided. Sections with require_drawn_signature=true must use 'drawn'.

use_saved_signature
boolean (Use Saved Signature)
Default: false

If true, apply the current user's saved profile signature instead of providing signature_data. The recorded method will be 'saved' and the section must not require a drawn signature.

Responses

Request samples

Content type
application/json
{
  • "section_id": "string",
  • "values": { },
  • "signature_data": "string",
  • "signature_method": "drawn",
  • "use_saved_signature": false
}

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",
  • "values": { }
}

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

SignatureMethod (string) or null

How the new signature was produced (drawn/typed/uploaded/saved).

use_saved_signature
boolean (Use Saved Signature)
Default: false

If true, apply the current user's saved profile signature.

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

Reason for amendment

Responses

Request samples

Content type
application/json
{
  • "values": { },
  • "signature_data": "string",
  • "signature_method": "drawn",
  • "use_saved_signature": false,
  • "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",
  • "values": { }
}

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",
  • "current_section_awaiting_user": false,
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "reference": "string",
  • "origin_instance_id": "string",
  • "permit_group_id": "string",
  • "requested_by_email": "string",
  • "allow_self_service": true,
  • "self_service_cap": 0,
  • "run_follow_on_agent_task": true,
  • "summary_values": [
    ],
  • "permissions": {
    },
  • "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)
OrganizationSecuritySettings (object) or null

Org-level security policy, including 2FA enforcement (APP-1319).

Run Form Follow On Agent Tasks (boolean) or Run Form Follow On Agent Tasks (null) (Run Form Follow On Agent Tasks)

Organisation-level default for whether a form's follow-on agent on-submit task runs when a form is submitted (APP-987).

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": {
    },
  • "security_settings": {
    },
  • "run_form_follow_on_agent_tasks": true
}

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
SignupAttribution (object) or null

First-touch marketing attribution captured at signup

SavedSignature (object) or null

Optional saved signature for re-use when completing form sections. Personal data — only exposed to the owning user.

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
is_service_context
boolean (Is Service Context)
Default: false

True if authenticated via M2M/service token (allows cross-org access)

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)

sso_managed
boolean (Sso Managed)
Default: false

True if this user's membership is managed by an enterprise SSO connection

Sso Connection Id (string) or Sso Connection Id (null) (Sso Connection Id)

ID of the SSO connection that provisioned this user, if any

idp_groups
Array of strings (Idp Groups)

Last-seen IdP groups from the SSO token/claims (for audit and role mapping)

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"
}

Get an organisation's security policy

Get the org-level security policy (2FA enforcement). Org admins only.

Authorizations:
HTTPBearer
path Parameters
org_id
required
string (Org Id)

Responses

Response samples

Content type
application/json
{
  • "require_2fa": false,
  • "require_2fa_for_project_access": false,
  • "require_2fa_for_org_admins": false,
  • "grace_period_days": 0,
  • "exempted_user_ids": [
    ],
  • "policy_updated_at": "2019-08-24T14:15:22Z"
}

Update an organisation's security policy

Update the org-level security policy (2FA enforcement). Org admins only.

Authorizations:
HTTPBearer
path Parameters
org_id
required
string (Org Id)
Request Body schema: application/json
required
require_2fa
boolean (Require 2Fa)
Default: false

Enforce 2FA for all users with org-level access (members of this org).

require_2fa_for_project_access
boolean (Require 2Fa For Project Access)
Default: false

Enforce 2FA for non-org / project-only collaborators (users belonging to OTHER orgs) accessing this organisation's projects.

require_2fa_for_org_admins
boolean (Require 2Fa For Org Admins)
Default: false

When set, enforce 2FA for org/billing admins even if require_2fa is off. When require_2fa is on this is implied for everyone.

Grace Period Days (integer) or Grace Period Days (null) (Grace Period Days)

Optional grace window (in days, measured from policy_updated_at) during which users without 2FA are not yet blocked. None means no grace period.

exempted_user_ids
Array of strings (Exempted User Ids)

User IDs explicitly exempted from this org's 2FA enforcement.

Policy Updated At (string) or Policy Updated At (null) (Policy Updated At)

When the security policy was last changed; the grace period is measured from this timestamp.

Responses

Request samples

Content type
application/json
{
  • "require_2fa": false,
  • "require_2fa_for_project_access": false,
  • "require_2fa_for_org_admins": false,
  • "grace_period_days": 0,
  • "exempted_user_ids": [
    ],
  • "policy_updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "require_2fa": false,
  • "require_2fa_for_project_access": false,
  • "require_2fa_for_org_admins": false,
  • "grace_period_days": 0,
  • "exempted_user_ids": [
    ],
  • "policy_updated_at": "2019-08-24T14:15:22Z"
}

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,
  • "next_cursor": "string"
}

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

Viewable Pdf Path (string) or Viewable Pdf Path (null) (Viewable Pdf Path)

R2 path to a viewable PDF rendition of the document. Populated for Word documents (.doc/.docx), which browsers cannot render natively, so the in-app viewer can fetch and display a PDF instead. PDFs are served from r2_path directly and leave this unset.

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

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

Hex digest of the document's raw bytes (SHA-256 by default). Indexed for content-based deduplication and submission-to-document matching (spec §4.2-4.3).

Content Hash Algo (string) or Content Hash Algo (null) (Content Hash Algo)

Algorithm used to compute content_hash (e.g. 'sha256')

DocumentSource (string) or null

How this document entered the system (upload, cde_sync, public_submission, …)

SourceSubmissionRef (object) or null

Back-reference to the public-page submission this document was ingested from. Set only when source == PUBLIC_SUBMISSION.

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

DrawingComparisonStatus (string) or null

Status of automatic drawing comparison for this document. PENDING means the comparison is deferred (e.g. parent still processing) and will be retried; NOT_APPLICABLE means no comparison is expected.

Comparison Status Reason (string) or Comparison Status Reason (null) (Comparison Status Reason)

Human-readable explanation for the current comparison_status.

Page Count (integer) or Page Count (null) (Page Count)

Number of pages detected for this document (PDF page count). None when the page count could not be determined.

Comparison Eligible (boolean) or Comparison Eligible (null) (Comparison Eligible)

Whether this document is eligible for drawing comparison. True for single-page documents, False for multi-page documents, None when eligibility could not be determined (e.g. unknown page count).

ComparisonEligibility (string) or null

Machine-readable reason for the comparison eligibility decision (e.g. eligible, excluded_multipage, unknown_page_count).

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

Document ID of the parent document this is an explicit revision of

removed_in_resubmission
boolean (Removed In Resubmission)
Default: false

Flagged when this document's slot/file was not re-supplied in a later resubmission for the same recipient+page. The document is never auto-deleted; this flag lets the UI surface the gap (spec §4.6).

Removed In Resubmission At (string) or Removed In Resubmission At (null) (Removed In Resubmission At)

When the document was flagged as removed-in-resubmission, if ever

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

is_latest
boolean (Is Latest)
Default: true

Whether this is the latest version

is_deleted
boolean (Is Deleted)
Default: false

Whether the document is deleted

PhotoMetadata (object) or null

EXIF and device metadata for photo documents (location, device, timestamp)

org_extraction_status
string (OrgExtractionStatus)
Default: "pending"
Enum: "pending" "success" "partial" "failed_enrichment" "failed_creation"

Status of organization extraction during document processing

Org Extraction Error (string) or Org Extraction Error (null) (Org Extraction Error)

Human-readable summary of the last org extraction error, if any

Extracted Organization (object) or Extracted Organization (null) (Extracted Organization)

Summary of the organization extracted from this document: {id, name, website_domain} or null.

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

AssigneeUser (object) or null

User who uploaded the document (overridden server-side)

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",
  • "viewable_pdf_path": "string",
  • "error": "string",
  • "error_detail": { },
  • "filename": "string",
  • "r2_path": "string",
  • "file_extension": "string",
  • "file_handling_tier": "RECORD_ONLY",
  • "content_hash": "string",
  • "content_hash_algo": "string",
  • "source": "upload",
  • "source_submission_ref": {
    },
  • "drawing_comparison_id": "string",
  • "comparison_status": "NOT_APPLICABLE",
  • "comparison_status_reason": "string",
  • "page_count": 0,
  • "comparison_eligible": true,
  • "comparison_eligibility_reason": "eligible",
  • "revision_of": "string",
  • "removed_in_resubmission": false,
  • "removed_in_resubmission_at": "2019-08-24T14:15:22Z",
  • "virtual_document_id": "string",
  • "virtual_document_version": 0,
  • "auto_generated": false,
  • "is_latest": true,
  • "is_deleted": false,
  • "photo_metadata": {
    },
  • "org_extraction_status": "pending",
  • "org_extraction_error": "string",
  • "extracted_organization": { },
  • "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": {
    },
  • "org_extraction_status": "pending",
  • "org_extraction_error": "string",
  • "extracted_organization": { },
  • "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",
  • "comparison_status": "NOT_APPLICABLE",
  • "comparison_status_reason": "string",
  • "page_count": 0,
  • "comparison_eligible": true,
  • "comparison_eligibility_reason": "eligible",
  • "revision_of": "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.

When start_date and/or end_date are supplied, only programme tasks whose planned window overlaps the requested range are returned. This trims the payload for large programmes instead of returning every task.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
query Parameters
Start Date (string) or Start Date (null) (Start Date)

Only include tasks whose planned window ends on or after this date

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

Only include tasks whose planned window starts on or before this date

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": { },
  • "is_deleted": false,
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "string",
  • "is_archived": false,
  • "archived_at": "2019-08-24T14:15:22Z",
  • "archived_by": "string",
  • "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)
query Parameters
include_archived
boolean (Include Archived)
Default: false

Include archived programme tasks (hidden by default).

include_deleted
boolean (Include Deleted)
Default: false

Include soft-deleted programme tasks (org admin only — soft-deleted records are retained for H&S / legal compliance).

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": { },
  • "is_deleted": false,
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "string",
  • "is_archived": false,
  • "archived_at": "2019-08-24T14:15:22Z",
  • "archived_by": "string",
  • "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": { },
  • "is_deleted": false,
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "string",
  • "is_archived": false,
  • "archived_at": "2019-08-24T14:15:22Z",
  • "archived_by": "string",
  • "created_by": "string",
  • "updated_by": "string"
}

Delete a programme task

Soft-delete a programme task.

Programme tasks are retained for H&S / legal compliance and never hard-deleted. Use the archive endpoint to hide a task from default UI lists.

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": [
    ]
}

Export Gantt chart as PDF

Export programme Gantt chart as a PDF file.

Args:

project_id: Project ID
page_size: Page size (a4, a3, letter, custom)
orientation: Page orientation (landscape, portrait)
start_date: Optional start of date range filter
end_date: Optional end of date range filter
current_user: Current authenticated user

Returns:

PDF file as downloadable response
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
query Parameters
page_size
string (PageSize)
Default: "a4"
Enum: "a4" "a3" "letter" "custom"

Supported page sizes.

orientation
string (Orientation)
Default: "landscape"
Enum: "landscape" "portrait"

Page orientation.

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

Responses

Response samples

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

Export Gantt chart as PNG

Export programme Gantt chart as a PNG image.

Args:

project_id: Project ID
page_size: Page size (a4, a3, letter, custom)
orientation: Page orientation (landscape, portrait)
start_date: Optional start of date range filter
end_date: Optional end of date range filter
scale: Resolution multiplier (default 2.0 for retina)
current_user: Current authenticated user

Returns:

PNG image as downloadable response
Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
query Parameters
page_size
string (PageSize)
Default: "a4"
Enum: "a4" "a3" "letter" "custom"

Supported page sizes.

orientation
string (Orientation)
Default: "landscape"
Enum: "landscape" "portrait"

Page orientation.

Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
scale
number (Scale)
Default: 2

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
include_dashboard
boolean (Include Dashboard)
Default: false
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,
  • "include_dashboard": false,
  • "metadata": { }
}

Response samples

Content type
application/json
null

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
null

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,
  • "dashboard_created": 0,
  • "dashboard_widgets_added": 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

Is Hrb (boolean) or Is Hrb (null) (Is Hrb)

Filter by Higher-Risk Building status. true = HRB only, false = non-HRB only, omit = all projects.

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

Scope the listing to a single organisation the caller belongs to. Defaults to the caller's currently active organisation. Projects owned by the caller's other organisations are excluded so an org switch cannot leak a stale cross-org project (APP-1299).

Responses

Response samples

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

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

Country (string) or Country (null) (Country)

ISO 3166-1 alpha-2 country code of the site (e.g. 'GB', 'US'); drives location-conditional knowledge packs.

Subdivision (string) or Subdivision (null) (Subdivision)

ISO 3166-2 sub-national code or bare subdivision of the site (e.g. 'US-CA' or 'CA') for sub-national packs.

Jurisdiction (string) or Jurisdiction (null) (Jurisdiction)

Explicit jurisdiction code overriding country/subdivision for knowledge-pack resolution (e.g. 'GB', 'US-CA', 'EU').

ProjectSectorEnum (string) or null

Project sector classification

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 deleted

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

is_sample
boolean (Is Sample)
Default: false

Flag indicating this project is a seeded sample (used for the onboarding 'safe to explore' badge).

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.

F10 Required (boolean) or F10 Required (null) (F10 Required)

Whether the project requires an HSE F10 notification under CDM 2015. Null means notifiability has not yet been assessed.

F10 Reference (string) or F10 Reference (null) (F10 Reference)

HSE-issued F10 notification reference number

F10 Submitted At (string) or F10 Submitted At (null) (F10 Submitted At)

Date the original F10 notification was submitted to HSE

F10 Period Start (string) or F10 Period Start (null) (F10 Period Start)

Start of the construction period covered by the F10 notification

F10 Period End (string) or F10 Period End (null) (F10 Period End)

End of the construction period covered by the F10 notification

F10StatusEnum (string) or null

Lifecycle status of the F10 notification

F10 Last Revised At (string) or F10 Last Revised At (null) (F10 Last Revised At)

Date the F10 notification was last revised

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

Free-text notes about the F10 notification

Expected Peak Workers (integer) or Expected Peak Workers (null) (Expected Peak Workers)

Expected peak number of workers on site simultaneously. Used together with project duration to derive F10 notifiability.

Expected Person Days (integer) or Expected Person Days (null) (Expected Person Days)

Expected total person-days of construction work. Used to derive F10 notifiability under CDM 2015.

Is Hrb (boolean) or Is Hrb (null) (Is Hrb)

Whether the project is a Higher-Risk Building under the Building Safety Act 2022. Drives Gateway 2/3 flows and which evidence is in scope. Null means HRB status has not yet been assessed.

Hrb Storeys (integer) or Hrb Storeys (null) (Hrb Storeys)

Number of storeys above ground level for the building.

Hrb Height M (number) or Hrb Height M (null) (Hrb Height M)

Height of the building in metres, measured to the top occupied storey.

Hrb Residential Units (integer) or Hrb Residential Units (null) (Hrb Residential Units)

Total number of residential units in the building.

HRBOccupationStatusEnum (string) or null

Whether the building is in occupation or not yet occupied.

HRBBuildCategoryEnum (string) or null

Build category for HRB scope: new build, Cat A alteration, or Cat B alteration.

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

Free-text notes about the HRB assessment.

audit_stop_work_flag
boolean (Audit Stop Work Flag)
Default: false

Whether the project is currently under an auditor-issued stop-work directive. Set automatically by the audit follow-up pipeline (APP-431) when an auditor submits an audit with stop_work_recommended=true.

Audit Stop Work At (string) or Audit Stop Work At (null) (Audit Stop Work At)

Timestamp at which the stop-work flag was raised.

Audit Stop Work Submission Id (string) or Audit Stop Work Submission Id (null) (Audit Stop Work Submission Id)

ID of the audit submission that triggered the stop-work flag.

Audit Stop Work Reason (string) or Audit Stop Work Reason (null) (Audit Stop Work Reason)

Reason captured by the auditor when raising stop-work.

WholeLifeCostParameters (object) or null

Whole-life-cost parameter set (study period, discount rate, maintenance regime, replacement cycles, energy price basis). Null means the project uses the standard ISO 15686-5 / HM Treasury Green Book defaults (APP-1337).

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,
  • "country": "string",
  • "subdivision": "string",
  • "jurisdiction": "string",
  • "sector": "residential",
  • "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",
  • "is_sample": false,
  • "completion_percentage": 0,
  • "organization_id": "string",
  • "license_id": "string",
  • "project_settings": {
    },
  • "custom_fields": { },
  • "custom_field_definitions": {
    },
  • "f10_required": true,
  • "f10_reference": "string",
  • "f10_submitted_at": "2019-08-24T14:15:22Z",
  • "f10_period_start": "2019-08-24T14:15:22Z",
  • "f10_period_end": "2019-08-24T14:15:22Z",
  • "f10_status": "not_required",
  • "f10_last_revised_at": "2019-08-24T14:15:22Z",
  • "f10_notes": "string",
  • "expected_peak_workers": 0,
  • "expected_person_days": 0,
  • "is_hrb": true,
  • "hrb_storeys": 0,
  • "hrb_height_m": 0,
  • "hrb_residential_units": 0,
  • "hrb_occupation_status": "in_occupation",
  • "hrb_build_category": "new_build",
  • "hrb_notes": "string",
  • "audit_stop_work_flag": false,
  • "audit_stop_work_at": "2019-08-24T14:15:22Z",
  • "audit_stop_work_submission_id": "string",
  • "audit_stop_work_reason": "string",
  • "wlc_parameters": {
    },
  • "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)
ProjectSectorEnum (string) or null
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)
StatusEnum (string) or null
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)
Is Sample (boolean) or Is Sample (null) (Is Sample)
ProjectSettings (object) or null
Custom Fields (object) or Custom Fields (null) (Custom Fields)
Custom Field Definitions (object) or Custom Field Definitions (null) (Custom Field Definitions)
F10 Required (boolean) or F10 Required (null) (F10 Required)
F10 Reference (string) or F10 Reference (null) (F10 Reference)
F10 Submitted At (string) or F10 Submitted At (null) (F10 Submitted At)
F10 Period Start (string) or F10 Period Start (null) (F10 Period Start)
F10 Period End (string) or F10 Period End (null) (F10 Period End)
F10StatusEnum (string) or null
F10 Last Revised At (string) or F10 Last Revised At (null) (F10 Last Revised At)
F10 Notes (string) or F10 Notes (null) (F10 Notes)
Expected Peak Workers (integer) or Expected Peak Workers (null) (Expected Peak Workers)
Expected Person Days (integer) or Expected Person Days (null) (Expected Person Days)
Is Hrb (boolean) or Is Hrb (null) (Is Hrb)
Hrb Storeys (integer) or Hrb Storeys (null) (Hrb Storeys)
Hrb Height M (number) or Hrb Height M (null) (Hrb Height M)
Hrb Residential Units (integer) or Hrb Residential Units (null) (Hrb Residential Units)
HRBOccupationStatusEnum (string) or null
HRBBuildCategoryEnum (string) or null
Hrb Notes (string) or Hrb Notes (null) (Hrb Notes)
WholeLifeCostParameters (object) or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "project_reference": "string",
  • "logo": "string",
  • "location": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "sector": "residential",
  • "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": [
    ],
  • "completion_percentage": 0,
  • "updated_by": "string",
  • "archived": true,
  • "archived_at": "2019-08-24T14:15:22Z",
  • "is_sample": true,
  • "project_settings": {
    },
  • "custom_fields": { },
  • "custom_field_definitions": {
    },
  • "f10_required": true,
  • "f10_reference": "string",
  • "f10_submitted_at": "2019-08-24T14:15:22Z",
  • "f10_period_start": "2019-08-24T14:15:22Z",
  • "f10_period_end": "2019-08-24T14:15:22Z",
  • "f10_status": "not_required",
  • "f10_last_revised_at": "2019-08-24T14:15:22Z",
  • "f10_notes": "string",
  • "expected_peak_workers": 0,
  • "expected_person_days": 0,
  • "is_hrb": true,
  • "hrb_storeys": 0,
  • "hrb_height_m": 0,
  • "hrb_residential_units": 0,
  • "hrb_occupation_status": "in_occupation",
  • "hrb_build_category": "new_build",
  • "hrb_notes": "string",
  • "wlc_parameters": {
    }
}

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"
}

Archive a project

Atomically archive a project, setting archived=true, status='archived' and archived_at together so any client stays consistent.

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"
}

Restore an archived project

Atomically restore a project, setting archived=false, status='active' and clearing archived_at together so any client stays consistent.

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"
}

Get the TW minor-workflow category allowlist

Return the categories that default to the minor workflow on this project.

New projects (no TWC opt-in yet) return an empty list.

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

Responses

Response samples

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

Replace the TW minor-workflow category allowlist

Replace the project's minor-workflow allowlist atomically (TWC-controlled).

Only a project's TWC, a project admin, or an org admin may mutate the list. Every successful PUT writes an audit entry capturing the actor, project and the before/after diff.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
categories
Array of strings (Categories)
Items Enum: "scaffold" "formwork" "falsework" "propping" "back_propping" "excavation_support" "sheet_piling" "cofferdam" "hoarding" "edge_protection" "temp_access" "crane_base" "mast_climber" "hoist" "other" "minor_screen" "dust_hoarding" "floor_protection" "signage_barrier"

Responses

Request samples

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

Response samples

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

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 .. 500 ]
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)
Search (string) or Search (null) (Search)

Case-insensitive search across member name, email, role and organisation name

Responses

Response samples

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

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,
  • "next_cursor": "string"
}

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

send_email
boolean (Send Email)
Default: true

Whether to send invitation email. Set false to create the record without emailing.

Responses

Request samples

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

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": [
    ]
}

Seed a sample project for onboarding

Create a safe-to-explore sample project populated with demonstration documents, a toolbox-talk form template, mock team members, one issued form and a few calendar events. Idempotent per user: subsequent calls by the same user return the existing sample project without creating duplicates.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "project_id": "string",
  • "route": "string",
  • "is_new": true
}

Get project onboarding status

Get onboarding (setup guide) progress for a specific project.

Returns only project-scoped workflows for the given project, including any phase-specific dynamic workflows. This is the dedicated counterpart to GET /api/v1/user/onboarding for project setup (BE-12 / §5.1).

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)
query Parameters
include_dynamic
boolean (Include Dynamic)
Default: true

Include dynamically generated phase-specific workflows

Responses

Response samples

Content type
application/json
{
  • "context": {
    },
  • "onboarding_complete": false,
  • "overall_progress_percentage": 40,
  • "suggestions": [
    ],
  • "user_id": "507f1f77bcf86cd799439011",
  • "workflows": [
    ]
}

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
Example
{
  • "resource_type": "string",
  • "category": "string",
  • "item": {
    },
  • "attachments": [
    ],
  • "organization": {
    },
  • "project": {
    },
  • "permissions": [
    ],
  • "share_info": {
    }
}

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
{
  • "instance_id": "string",
  • "instance_type": "string",
  • "title": "string",
  • "instructions": "string",
  • "expires_at": "string",
  • "schema": { },
  • "ui_schema": { },
  • "prefill_values": { },
  • "locked_field_ids": [
    ],
  • "hidden_field_ids": [
    ],
  • "organization": { },
  • "project": { },
  • "allow_self_service": false,
  • "can_request_another": false,
  • "hub_token": "string",
  • "reference": "string",
  • "summary_values": [
    ],
  • "has_workflow": false,
  • "workflow_config": { },
  • "workflow_status": "pending"
}

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
{ }

Request Another Permit

Clone the current permit instance into a fresh sibling and return its share token.

The new instance inherits template, pinned version, prefill/locked/hidden fields, workflow config and expiry policy from the source. It opens in ISSUED / PENDING and is reachable via its own public share URL. The supplied completer_email is stored as requested_by_email so approval notifications can be routed back to the requester.

Returns 409 Conflict with a clear, cap-citing message when the self-service cap for this permit family has been reached, and 400 when self-service is not enabled for the permit type. The frontend surfaces these as a toast.

path Parameters
share_token
required
string (Share Token)
Request Body schema: application/json
required
Completer Name (string) or Completer Name (null) (Completer Name)
completer_email
required
string (Completer Email)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "instance_id": "string",
  • "share_token": "string",
  • "permit_group_id": "string"
}

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",
  • "values": { }
}

Get Public Section Completions

Return latest completion (with values) for every section on this instance.

Use this to populate the form view for the next assignee so they can see what previous parties have submitted.

path Parameters
share_token
required
string (Share Token)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Public Section Completion History

Return full revision history (with values) for a single section.

path Parameters
share_token
required
string (Share Token)
section_id
required
string (Section Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

public-pages

public-pages endpoints

Get Public Page

Get a public page by its share token for external display.

Returns page content, blocks, branding, and configuration needed to render the page in the frontend. Does not enforce email/password gating so the frontend can render the verification step.

path Parameters
share_token
required
string (Share Token)

Responses

Response samples

Content type
application/json
{ }

Verify Page Access

Verify identity for accessing a public page.

Depending on the page's verification method, the visitor provides their email (for email-match or email-code verification) or an access code.

path Parameters
share_token
required
string (Share Token)
Request Body schema: application/json
required
Email (string) or Email (null) (Email)
Access Code (string) or Access Code (null) (Access Code)

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Submit Public Page

Submit data on a public page.

External parties use this endpoint to submit their information (uploaded files, free text, form field answers). This may trigger a workflow or agent-task for validation.

path Parameters
share_token
required
string (Share Token)
Request Body schema: application/json
required
submitter_name
required
string (Submitter Name) <= 200 characters
submitter_email
required
string (Submitter Email) <= 320 characters
object (Values)
Array of objects (Uploaded Files)
Resubmission Of (string) or Resubmission Of (null) (Resubmission Of)

Responses

Request samples

Content type
application/json
{
  • "submitter_name": "string",
  • "submitter_email": "string",
  • "values": { },
  • "uploaded_files": [
    ],
  • "resubmission_of": "string"
}

Response samples

Content type
application/json
{
  • "submission_id": "string",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "submitter_name": "string",
  • "submitter_email": "string",
  • "values": { },
  • "uploaded_files": [
    ],
  • "verification_method": "string",
  • "verified_at": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "review_notes": "string",
  • "resubmission_of": "string",
  • "generated_report_id": "string",
  • "generated_report_error": "string"
}

Presign Attachment Upload

Get a presigned URL for uploading a file to a public page.

The client uploads the file directly to cloud storage using the returned URL, then confirms the upload via the confirm endpoint.

path Parameters
share_token
required
string (Share Token)
Request Body schema: application/json
required
filename
required
string (Filename)
content_type
required
string (Content Type)
size_bytes
required
integer (Size Bytes) >= 1

Responses

Request samples

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

Response samples

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

Download Page Document

Get a presigned download URL for a project document linked to the page.

Only documents explicitly listed in the page's downloadable_document_ids are accessible.

path Parameters
share_token
required
string (Share Token)
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
{ }

Get Submission Status

Get the status and feedback for a specific submission.

External parties use this to check whether their submission was accepted, rejected, or requires changes.

path Parameters
share_token
required
string (Share Token)
submission_id
required
string (Submission Id)

Responses

Response samples

Content type
application/json
{ }

Create Public Page

Create a new public page.

Creates a configurable page accessible by external parties via a share link. Automatically creates an associated public share and optionally sends an invitation email to the recipient.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
title
required
string (Title) <= 300 characters
Description (string) or Description (null) (Description)
page_type
required
string (Page Type) <= 100 characters
project_id
required
string (Project Id)
Workspace Item Id (string) or Workspace Item Id (null) (Workspace Item Id)
Lifecycle Code (string) or Lifecycle Code (null) (Lifecycle Code)
Recipient Name (string) or Recipient Name (null) (Recipient Name)
Recipient Email (string) or Recipient Email (null) (Recipient Email)
Recipient Company (string) or Recipient Company (null) (Recipient Company)
Recipient Company Id (string) or Recipient Company Id (null) (Recipient Company Id)
Array of objects (Blocks)
downloadable_document_ids
Array of strings (Downloadable Document Ids)
Array of Allowed Upload Types (strings) or Allowed Upload Types (null) (Allowed Upload Types)
Max Upload Size Mb (integer) or Max Upload Size Mb (null) (Max Upload Size Mb)
Max Uploads (integer) or Max Uploads (null) (Max Uploads)
verification_method
string (VerificationMethod)
Default: "email_match"
Enum: "email_code" "access_code" "email_match" "none"

Methods for verifying the identity of a page visitor.

Access Code (string) or Access Code (null) (Access Code)

Plain-text access code (will be hashed before storage)

On Submit Workflow Config Id (string) or On Submit Workflow Config Id (null) (On Submit Workflow Config Id)
On Submit Agent Task Id (string) or On Submit Agent Task Id (null) (On Submit Agent Task Id)
On Submit Stage Transition (string) or On Submit Stage Transition (null) (On Submit Stage Transition)
On Accept Stage Transition (string) or On Accept Stage Transition (null) (On Accept Stage Transition)
On Accept Agent Task Id (string) or On Accept Agent Task Id (null) (On Accept Agent Task Id)
On Reject Agent Task Id (string) or On Reject Agent Task Id (null) (On Reject Agent Task Id)
On Resubmission Agent Task Id (string) or On Resubmission Agent Task Id (null) (On Resubmission Agent Task Id)
DocumentIngestionConfig (object) or null
Max Submissions (integer) or Max Submissions (null) (Max Submissions)
allow_resubmission
boolean (Allow Resubmission)
Default: true
notify_on_submit_user_ids
Array of strings (Notify On Submit User Ids)
notify_on_accept_user_ids
Array of strings (Notify On Accept User Ids)
notify_recipient_on_accept
boolean (Notify Recipient On Accept)
Default: true
notify_recipient_on_reject
boolean (Notify Recipient On Reject)
Default: true
notify_recipient_on_resubmission_request
boolean (Notify Recipient On Resubmission Request)
Default: true
Expires In Days (integer) or Expires In Days (null) (Expires In Days)
send_invitation_email
boolean (Send Invitation Email)
Default: true

Send an invitation email to the recipient on creation

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "page_type": "string",
  • "project_id": "string",
  • "workspace_item_id": "string",
  • "lifecycle_code": "string",
  • "recipient_name": "string",
  • "recipient_email": "string",
  • "recipient_company": "string",
  • "recipient_company_id": "string",
  • "blocks": [
    ],
  • "downloadable_document_ids": [
    ],
  • "allowed_upload_types": [
    ],
  • "max_upload_size_mb": 1,
  • "max_uploads": 1,
  • "verification_method": "email_code",
  • "access_code": "string",
  • "on_submit_workflow_config_id": "string",
  • "on_submit_agent_task_id": "string",
  • "on_submit_stage_transition": "string",
  • "on_accept_stage_transition": "string",
  • "on_accept_agent_task_id": "string",
  • "on_reject_agent_task_id": "string",
  • "on_resubmission_agent_task_id": "string",
  • "document_ingestion_config": {
    },
  • "max_submissions": 0,
  • "allow_resubmission": true,
  • "notify_on_submit_user_ids": [
    ],
  • "notify_on_accept_user_ids": [
    ],
  • "notify_recipient_on_accept": true,
  • "notify_recipient_on_reject": true,
  • "notify_recipient_on_resubmission_request": true,
  • "expires_in_days": 1,
  • "send_invitation_email": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "description": "string",
  • "status": "draft",
  • "page_type": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "created_by": "string",
  • "created_by_name": "string",
  • "workspace_item_id": "string",
  • "workspace_item_ref": "string",
  • "lifecycle_code": "string",
  • "recipient_name": "string",
  • "recipient_email": "string",
  • "recipient_company": "string",
  • "recipient_company_id": "string",
  • "blocks": [
    ],
  • "downloadable_document_ids": [
    ],
  • "allowed_upload_types": [
    ],
  • "max_upload_size_mb": 0,
  • "max_uploads": 0,
  • "verification_method": "email_code",
  • "on_submit_workflow_config_id": "string",
  • "on_submit_agent_task_id": "string",
  • "on_submit_stage_transition": "string",
  • "on_accept_stage_transition": "string",
  • "on_accept_agent_task_id": "string",
  • "on_reject_agent_task_id": "string",
  • "on_resubmission_agent_task_id": "string",
  • "document_ingestion_config": {
    },
  • "submissions": [
    ],
  • "max_submissions": 0,
  • "allow_resubmission": true,
  • "notify_on_submit_user_ids": [
    ],
  • "notify_on_accept_user_ids": [
    ],
  • "notify_recipient_on_accept": true,
  • "notify_recipient_on_reject": true,
  • "notify_recipient_on_resubmission_request": true,
  • "share_id": "string",
  • "share_token": "string",
  • "share_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Public Pages

List public pages for the current organization.

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

Filter by project ID

PublicPageStatus (string) or Status (null) (Status)
Page Type (string) or Page Type (null) (Page Type)

Filter by page type

skip
integer (Skip) >= 0
Default: 0
limit
integer (Limit) [ 1 .. 100 ]
Default: 50

Responses

Response samples

Content type
application/json
{ }

Get Public Page

Get a public page by ID.

Authorizations:
HTTPBearer
path Parameters
page_id
required
string (Page Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "description": "string",
  • "status": "draft",
  • "page_type": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "created_by": "string",
  • "created_by_name": "string",
  • "workspace_item_id": "string",
  • "workspace_item_ref": "string",
  • "lifecycle_code": "string",
  • "recipient_name": "string",
  • "recipient_email": "string",
  • "recipient_company": "string",
  • "recipient_company_id": "string",
  • "blocks": [
    ],
  • "downloadable_document_ids": [
    ],
  • "allowed_upload_types": [
    ],
  • "max_upload_size_mb": 0,
  • "max_uploads": 0,
  • "verification_method": "email_code",
  • "on_submit_workflow_config_id": "string",
  • "on_submit_agent_task_id": "string",
  • "on_submit_stage_transition": "string",
  • "on_accept_stage_transition": "string",
  • "on_accept_agent_task_id": "string",
  • "on_reject_agent_task_id": "string",
  • "on_resubmission_agent_task_id": "string",
  • "document_ingestion_config": {
    },
  • "submissions": [
    ],
  • "max_submissions": 0,
  • "allow_resubmission": true,
  • "notify_on_submit_user_ids": [
    ],
  • "notify_on_accept_user_ids": [
    ],
  • "notify_recipient_on_accept": true,
  • "notify_recipient_on_reject": true,
  • "notify_recipient_on_resubmission_request": true,
  • "share_id": "string",
  • "share_token": "string",
  • "share_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Public Page

Update a public page.

Authorizations:
HTTPBearer
path Parameters
page_id
required
string (Page Id)
Request Body schema: application/json
required
Title (string) or Title (null) (Title)
Description (string) or Description (null) (Description)
PublicPageStatus (string) or null
Array of Blocks (objects) or Blocks (null) (Blocks)
Array of Downloadable Document Ids (strings) or Downloadable Document Ids (null) (Downloadable Document Ids)
Recipient Name (string) or Recipient Name (null) (Recipient Name)
Recipient Email (string) or Recipient Email (null) (Recipient Email)
Recipient Company (string) or Recipient Company (null) (Recipient Company)
Array of Notify On Submit User Ids (strings) or Notify On Submit User Ids (null) (Notify On Submit User Ids)
Array of Notify On Accept User Ids (strings) or Notify On Accept User Ids (null) (Notify On Accept User Ids)
Expires In Days (integer) or Expires In Days (null) (Expires In Days)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "status": "draft",
  • "blocks": [
    ],
  • "downloadable_document_ids": [
    ],
  • "recipient_name": "string",
  • "recipient_email": "string",
  • "recipient_company": "string",
  • "notify_on_submit_user_ids": [
    ],
  • "notify_on_accept_user_ids": [
    ],
  • "expires_in_days": 1
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "description": "string",
  • "status": "draft",
  • "page_type": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "created_by": "string",
  • "created_by_name": "string",
  • "workspace_item_id": "string",
  • "workspace_item_ref": "string",
  • "lifecycle_code": "string",
  • "recipient_name": "string",
  • "recipient_email": "string",
  • "recipient_company": "string",
  • "recipient_company_id": "string",
  • "blocks": [
    ],
  • "downloadable_document_ids": [
    ],
  • "allowed_upload_types": [
    ],
  • "max_upload_size_mb": 0,
  • "max_uploads": 0,
  • "verification_method": "email_code",
  • "on_submit_workflow_config_id": "string",
  • "on_submit_agent_task_id": "string",
  • "on_submit_stage_transition": "string",
  • "on_accept_stage_transition": "string",
  • "on_accept_agent_task_id": "string",
  • "on_reject_agent_task_id": "string",
  • "on_resubmission_agent_task_id": "string",
  • "document_ingestion_config": {
    },
  • "submissions": [
    ],
  • "max_submissions": 0,
  • "allow_resubmission": true,
  • "notify_on_submit_user_ids": [
    ],
  • "notify_on_accept_user_ids": [
    ],
  • "notify_recipient_on_accept": true,
  • "notify_recipient_on_reject": true,
  • "notify_recipient_on_resubmission_request": true,
  • "share_id": "string",
  • "share_token": "string",
  • "share_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Close Public Page

Close a public page and revoke its share link.

Authorizations:
HTTPBearer
path Parameters
page_id
required
string (Page Id)

Responses

Response samples

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

Accept Submission

Accept a submission on a public page.

Authorizations:
HTTPBearer
path Parameters
page_id
required
string (Page Id)
submission_id
required
string (Submission Id)
Request Body schema: application/json
Any of
Review Notes (string) or Review Notes (null) (Review Notes)
Any of
string (Review Notes)

Responses

Request samples

Content type
application/json
Example
{
  • "review_notes": "string"
}

Response samples

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

Reject Submission

Reject a submission on a public page.

Authorizations:
HTTPBearer
path Parameters
page_id
required
string (Page Id)
submission_id
required
string (Submission Id)
Request Body schema: application/json
required
Review Notes (string) or Review Notes (null) (Review Notes)
Any of
string (Review Notes)

Responses

Request samples

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

Response samples

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

Request Resubmission

Request resubmission with feedback notes.

Authorizations:
HTTPBearer
path Parameters
page_id
required
string (Page Id)
submission_id
required
string (Submission Id)
Request Body schema: application/json
required
Review Notes (string) or Review Notes (null) (Review Notes)
Any of
string (Review Notes)

Responses

Request samples

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

Response samples

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

Retry Submission Review

Re-queue the on-submit agent task for a failed submission (APP-390).

Looks up the page that owns the submission within the caller's organisation, clears any captured generated_report_error and stale generated_report_id on the submission, then re-enqueues the page's on-submit agent task. The frontend banner / triage tile will return to the in-progress state on the next refetch.

Authorizations:
HTTPBearer
path Parameters
submission_id
required
string (Submission Id)

Responses

Response samples

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

public-permits

public-permits endpoints

Get Permit Hub

Resolve a permit hub for a returning recipient (APP-800).

Args:

hub_token: Opaque per-recipient hub token.
email: Recipient email for the verification gate.
db: Database client.

Returns:

The recipient's permits for this hub's project/template.

Raises:

HTTPException: 404 if the hub is unknown, 401 if email is required,
    403 if the email does not match the hub recipient.
path Parameters
hub_token
required
string (Hub Token)
query Parameters
Email (string) or Email (null) (Email)

Responses

Response samples

Content type
application/json
{
  • "hub_token": "string",
  • "recipient_email": "string",
  • "permit_count": 0,
  • "can_request_another": false,
  • "permits": [
    ]
}

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" "public_page" "workspace_item"

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,
  • "next_cursor": "string"
}

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" "plant"

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,
  • "next_cursor": "string"
}

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" "BIM" "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

Approval Status (string) or Approval Status (null) (Approval Status)

Optional approval gate (opt-in). When omitted the report is created live with no review gate (default behaviour). When set it must be one of the ApprovalStatus values (pending / in_progress / approved / rejected / revoked).

Responses

Request samples

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

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,
  • "approval_status": "string",
  • "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
created_at_start: Optional start datetime filter (inclusive)
created_at_end: Optional end datetime filter (inclusive)
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

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

Return reports created on or after this datetime

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

Return reports created on or before this datetime

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,
  • "next_cursor": "string"
}

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,
  • "approval_status": "string",
  • "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,
  • "approval_status": "string",
  • "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"
}

Restore Report

Restore (un-delete) a soft-deleted report. Org-admin only (APP-819).

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,
  • "next_cursor": "string"
}

Get Report Versions

List previous-version metadata for a report (no content payload).

Use GET /reports/{report_id}/versions/{version}/content to fetch the actual content for a specific version.

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,
  • "next_cursor": "string"
}

Get Report Version Content

Return the content payload for a specific previous version.

Content may be served inline from Mongo or fetched transparently from R2 when the snapshot was tiered off for size reasons.

Authorizations:
HTTPBearer
path Parameters
report_id
required
string (Report Id)
version
required
integer (Version)

Responses

Response samples

Content type
application/json
{
  • "version": 0,
  • "content": "string"
}

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 and pagination.

Args:

project_id: Project ID
status: Filter by task status
assigned_to: Filter by assigned user ID
task_type: Filter by task type (manual, programme, automated)
page: Page number (1-based)
size: Number of items per page
include_archived: Include archived records (hidden by default)
include_deleted: Include soft-deleted records (org admin only)
current_user: Current authenticated user

Returns:

Paginated 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)
TaskType (string) or Task Type (null) (Task Type)
page
integer (Page) >= 1
Default: 1

Page number (1-based).

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

Number of items per page (max 100).

include_archived
boolean (Include Archived)
Default: false

Include archived tasks (hidden by default).

include_deleted
boolean (Include Deleted)
Default: false

Include soft-deleted tasks (org admin only — soft-deleted records are retained for H&S / legal compliance and normally hidden from the UI).

Responses

Response samples

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

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

task_type
string (TaskType)
Default: "manual"
Enum: "manual" "programme" "automated"

Type of task: manual, programme, or automated

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" "urgent"

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)

DEPRECATED (APP-851): use document_ids for multi-document links. Retained for backward compatibility for one release.

Related Object Type (string) or Related Object Type (null) (Related Object Type)

DEPRECATED (APP-851): use document_ids for document links.

document_ids
Array of strings (Document Ids)

Canonical multi-document link field (APP-851).

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

Source Submission Id (string) or Source Submission Id (null) (Source Submission Id)

FormSubmission ID this task was raised from (APP-341)

Source Item Index (integer) or Source Item Index (null) (Source Item Index)

0-based index of the flagged item within the submission's repeater values (APP-341).

TaskSchedule (object) or null

Scheduling configuration for recurring or one-time execution

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

Planned start date

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

Planned end date

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

Float Days (number) or Float Days (null) (Float Days)

Float days in the schedule

milestone_ids
Array of strings (Milestone Ids)

Milestone IDs

Phase (string) or Phase (null) (Phase)

Phase designation

on_critical_path
boolean (On Critical Path)
Default: false

Whether task is on the critical path

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "task_type": "manual",
  • "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",
  • "document_ids": [
    ],
  • "project_id": "string",
  • "created_by": "string",
  • "closed_reason": "string",
  • "closed_reason_code": "document_revised",
  • "source_submission_id": "string",
  • "source_item_index": 0,
  • "schedule": {
    },
  • "planned_start": "2019-08-24T14:15:22Z",
  • "planned_end": "2019-08-24T14:15:22Z",
  • "adjusted_start": "2019-08-24T14:15:22Z",
  • "adjusted_end": "2019-08-24T14:15:22Z",
  • "float_days": 0,
  • "milestone_ids": [
    ],
  • "phase": "string",
  • "on_critical_path": false
}

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)
TaskType (string) or null
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)
Array of Document Ids (strings) or Document Ids (null) (Document Ids)
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
Planned Start (string) or Planned Start (null) (Planned Start)
Planned End (string) or Planned End (null) (Planned End)
Adjusted Start (string) or Adjusted Start (null) (Adjusted Start)
Adjusted End (string) or Adjusted End (null) (Adjusted End)
Float Days (number) or Float Days (null) (Float Days)
Array of Milestone Ids (strings) or Milestone Ids (null) (Milestone Ids)
Phase (string) or Phase (null) (Phase)
On Critical Path (boolean) or On Critical Path (null) (On Critical Path)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "task_type": "manual",
  • "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",
  • "document_ids": [
    ],
  • "updated_by": "string",
  • "closed_reason": "string",
  • "closed_reason_code": "document_revised",
  • "schedule": {
    },
  • "planned_start": "2019-08-24T14:15:22Z",
  • "planned_end": "2019-08-24T14:15:22Z",
  • "adjusted_start": "2019-08-24T14:15:22Z",
  • "adjusted_end": "2019-08-24T14:15:22Z",
  • "float_days": 0,
  • "milestone_ids": [
    ],
  • "phase": "string",
  • "on_critical_path": true
}

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"
}

Batch Create Tasks

Create multiple tasks in a single request.

Designed for agent workflows that process form submissions and generate a list of action tasks. Each item uses title, assignee_role, and due_date_offset (days from today) rather than the standard TaskCreate field names. Unknown fields are folded into tags or the task description rather than causing a validation error.

The tasks body field accepts:

  • A JSON string (the raw LLM step output).
  • A dict with a tasks array.
  • A plain list of task objects.

Args:

request: Batch task creation request.
current_user: Authenticated user (must have project access).
db: Database connection.

Returns:

``TaskBatchResult`` with successfully created tasks and any per-item
failures.

Raises:

HTTPException 400: If ``project_id`` is invalid or ``tasks`` cannot
    be parsed.
HTTPException 403: If the user is not authorised for the project.
HTTPException 404: If the project does not exist.
Authorizations:
HTTPBearer
Request Body schema: application/json
required
project_id
required
string (Project Id)

Project to create tasks in.

tasks
required
any (Tasks)

Tasks to create. May be a JSON string, a dict with a 'tasks' array, or a list of task objects.

Source (object) or Source (null) (Source)

Source metadata (e.g. form submission reference).

Responses

Request samples

Content type
application/json
{
  • "project_id": "string",
  • "tasks": null,
  • "source": { }
}

Response samples

Content type
application/json
{
  • "created": [
    ],
  • "failed": [
    ],
  • "total": 0,
  • "created_count": 0,
  • "failed_count": 0
}

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" "progress_report" "inspection_report" "compliance_report" "project_report" "project_document" "general_report" "general_document" "building_user_guide" "building_log_book" "commissioning_report" "handover_document" "operations_manual" "design_report" "sustainability_report" "fire_strategy" "waste_management_plan" "traffic_management_plan" "travel_plan" "tender_report" "cost_report" "programme_report" "environmental_impact_assessment" "asset_register" "nec_early_warning_log" "nec_programme_submission" "ground_investigation_report" "ceequal_report" "utility_plans" "infrastructure_monthly_report" "asset_handover_pack" "interface_management_plan" "stakeholder_engagement_plan" "bim_execution_plan"

Supported virtual document template types.

scope
string (TemplateScope)
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)'.

Iu Cost Override (number) or Iu Cost Override (null) (Iu Cost Override)

Fixed IU charge for generating a document from this template. When set, this exact value is charged and shown instead of the section-based estimate. Set per-template in planops-configs as a subjective high/medium/low rating (3/2/1).

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",
  • "iu_cost_override": 0,
  • "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.

When project_id is provided, returns all templates available for that project:

  • APP-scoped system templates (if include_app_templates=true)
  • ORG-scoped templates belonging to the project's organization
  • PROJECT-scoped templates where the project is in the template's project_ids
Authorizations:
HTTPBearer
query Parameters
Organization Id (string) or Organization Id (null) (Organization Id)
Project Id (string) or Project Id (null) (Project Id)

Filter templates available for a specific project. Returns APP templates, ORG templates for the project's organization, and PROJECT templates assigned to this project.

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
  • Request is via M2M/service token (allows cross-org access)
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
Iu Cost Override (number) or Iu Cost Override (null) (Iu Cost Override)

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": {
    },
  • "iu_cost_override": 0
}

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)
query Parameters
diff_format
string (Diff Format)
Default: "structured"
Enum: "structured" "raw"

Diff payload format. 'structured' (default) emits field_changes; 'raw' emits legacy old_value/new_value blobs for debugging.

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

recipient_user_ids
Array of strings (Recipient User Ids)

Project members to receive the issued document version (APP-542).

notify
boolean (Notify)
Default: true

If True and recipient_user_ids is non-empty, send DOCUMENT_ISSUED notifications.

Responses

Request samples

Content type
application/json
{
  • "template_id": "string",
  • "project_id": "string",
  • "title": "string",
  • "user_inputs": { },
  • "document_references": [
    ],
  • "recipient_user_ids": [
    ],
  • "notify": true
}

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": { },
  • "generation_inputs": { },
  • "document_references": [
    ],
  • "revision_summary": "string",
  • "recipients": [
    ],
  • "issued_at": "2019-08-24T14:15:22Z",
  • "issued_by": "string",
  • "is_edited": false,
  • "edited_by": "string",
  • "edited_at": "2019-08-24T14:15:22Z",
  • "is_deleted": false,
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "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
include_generation_inputs
boolean (Include Generation Inputs)
Default: true

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": { },
  • "generation_inputs": { },
  • "document_references": [
    ],
  • "revision_summary": "string",
  • "recipients": [
    ],
  • "issued_at": "2019-08-24T14:15:22Z",
  • "issued_by": "string",
  • "is_edited": false,
  • "edited_by": "string",
  • "edited_at": "2019-08-24T14:15:22Z",
  • "is_deleted": false,
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "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)
Array of Recipient User Ids (strings) or Recipient User Ids (null) (Recipient User Ids)

Recipients for the new version. Only accepted when the patch creates a new version (APP-542).

notify
boolean (Notify)
Default: true

If True and recipients are provided, dispatch DOCUMENT_ISSUED notifications.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "metadata": { },
  • "status": "draft",
  • "approval_status": "pending",
  • "content": "string",
  • "content_format": "html",
  • "user_inputs": { },
  • "document_references": [
    ],
  • "recipient_user_ids": [
    ],
  • "notify": true
}

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": { },
  • "generation_inputs": { },
  • "document_references": [
    ],
  • "revision_summary": "string",
  • "recipients": [
    ],
  • "issued_at": "2019-08-24T14:15:22Z",
  • "issued_by": "string",
  • "is_edited": false,
  • "edited_by": "string",
  • "edited_at": "2019-08-24T14:15:22Z",
  • "is_deleted": false,
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "string"
}

Delete Virtual Document

Soft-delete a generated virtual document (APP-816).

Sets is_deleted=True, deleted_at and deleted_by on the document row, mirroring the soft-delete behaviour of uploaded documents and reports. Auth: the document's creator or an org admin of the owning organization.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

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

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
}

Get Document Version By Document Id

Fetch the historical snapshot of a specific version, looked up by its own document_id.

Use this variant when version_number is not guaranteed unique across template revisions. Returns the version row as it was stored at generation time (no re-rendering).

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
prior_document_id
required
string (Prior Document Id)
query Parameters
include_data_snapshot
boolean (Include Data Snapshot)
Default: false
include_generation_inputs
boolean (Include Generation Inputs)
Default: true

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": { },
  • "generation_inputs": { },
  • "document_references": [
    ],
  • "revision_summary": "string",
  • "recipients": [
    ],
  • "issued_at": "2019-08-24T14:15:22Z",
  • "issued_by": "string",
  • "is_edited": false,
  • "edited_by": "string",
  • "edited_at": "2019-08-24T14:15:22Z",
  • "is_deleted": false,
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "string"
}

Get Document Version By Number

Fetch the historical snapshot of a specific version of a virtual document.

Returns the version row as it was stored at generation time. Content is byte-identical to what was rendered at generation; no re-rendering against current templates/data is performed.

RBAC mirrors GET /documents/{document_id}: viewer of the current document can view history.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
version_number
required
integer (Version Number)
query Parameters
include_data_snapshot
boolean (Include Data Snapshot)
Default: false
include_generation_inputs
boolean (Include Generation Inputs)
Default: true

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": { },
  • "generation_inputs": { },
  • "document_references": [
    ],
  • "revision_summary": "string",
  • "recipients": [
    ],
  • "issued_at": "2019-08-24T14:15:22Z",
  • "issued_by": "string",
  • "is_edited": false,
  • "edited_by": "string",
  • "edited_at": "2019-08-24T14:15:22Z",
  • "is_deleted": false,
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "string"
}

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.

create_project_document
boolean (Create Project Document)
Default: true

If true, create a project document record and queue processing. Set to false for preview-only PDF downloads that skip analysis.

Responses

Request samples

Content type
application/json
{
  • "purpose": "manual_export",
  • "upload_to_agentcon": false,
  • "filename": "string",
  • "agentcon_metadata": { },
  • "create_project_document": true
}

Response samples

Content type
application/json
{
  • "export": {
    },
  • "download_url": "string",
  • "agentcon_document": { }
}

Author Document Version

Persist hand-authored content as a new version without regenerating (APP-761).

Clones the prior version's metadata, increments version_number, marks the prior version superseded, and stamps the new version with edit provenance (generation_trigger=EDITED, is_edited=True, edited_by/edited_at). The assembly engine is never invoked.

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

Hand-authored content for the new version.

OutputFormat (string) or null

Format of the authored content. Defaults to the prior version's content_format.

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

Optional new title; defaults to the prior version's title.

Metadata (object) or Metadata (null) (Metadata)

Optional metadata overrides applied to the new version.

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "content_format": "html",
  • "title": "string",
  • "metadata": { }
}

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": { },
  • "generation_inputs": { },
  • "document_references": [
    ],
  • "revision_summary": "string",
  • "recipients": [
    ],
  • "issued_at": "2019-08-24T14:15:22Z",
  • "issued_by": "string",
  • "is_edited": false,
  • "edited_by": "string",
  • "edited_at": "2019-08-24T14:15:22Z",
  • "is_deleted": false,
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "string"
}

Regenerate Document Prefill

Return the resolved selections that would seed a regenerate request.

Lets the FE prefill the regenerate panel before submission.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
{
  • "document_id": "string",
  • "template_id": "string",
  • "project_id": "string",
  • "title": "string",
  • "version_number": 0,
  • "generation_inputs": { },
  • "reconstructed": false
}

Regenerate Document

Regenerate a document, seeding from the prior version's persisted selections.

By default this runs synchronously and returns the new VirtualDocument (a freshly-superseding version of the source). Pass queue=true to fall back to the legacy enqueue behaviour.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
Request Body schema: application/json
Any of
User Inputs (object) or User Inputs (null) (User Inputs)

Overrides merged over the prior document's generation_inputs.

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

Optional new title; defaults to the prior document's title.

queue
boolean (Queue)
Default: false

If True, enqueue a RegenerationJob (legacy behaviour) instead of generating synchronously. The job will still seed from the prior document's generation_inputs.

Responses

Request samples

Content type
application/json
Example
{
  • "user_inputs": { },
  • "title": "string",
  • "queue": false
}

Response samples

Content type
application/json
{ }

Issue Document Version

Issue a previously-saved version to recipients (APP-542 §6.3).

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
version_id
required
string (Version Id)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Get Document Distribution

Per-version + cross-version distribution summary (APP-542 §6.3).

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
null

List Version Recipients

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

Responses

Response samples

Content type
application/json
null

Add Version Recipients

Add recipients to the latest version (older versions are frozen).

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
version_id
required
string (Version Id)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Remove Version Recipient

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
version_id
required
string (Version Id)
user_id
required
string (User Id)

Responses

Response samples

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

Record Version View

Record that the current user viewed this version and track review dwell time.

Actions (request body action):

  • open (default) - stamps first_viewed_at/last_viewed_at and marks the recipient VIEWED; emits the existing VIEWED activity on first view.
  • heartbeat - periodic ping while actively viewing; extends the coarse, capped active-review duration.
  • close - finalises the review, persists reviewed_at and emits the server-side document_reviewed analytics event (compliance evidence).
Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)
version_id
required
string (Version Id)
Request Body schema: application/json
Any of
action
string (Action)
Default: "open"
Enum: "open" "heartbeat" "close"

Responses

Request samples

Content type
application/json
Example
{
  • "action": "open"
}

Response samples

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

Get Previous Recipients

Return the user_ids issued on the most recent prior issued version.

Used by the FE to pre-fill the recipient picker on regenerate / edit-flow.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

Content type
application/json
null

Restore Virtual Document

Restore (un-delete) a soft-deleted generated virtual document (APP-819).

Clears is_deleted, deleted_at and deleted_by. Org-admin only — restricted to admins of the document's owning organization.

Authorizations:
HTTPBearer
path Parameters
document_id
required
string (Document Id)

Responses

Response samples

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