Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Financial Management

Owner Reports

31 endpoints31 implementedAll modules →
  1. GET /rest/v1.0/companies/{company_id}/owner_reportsList portfolio owner reports
  2. POST /rest/v1.0/companies/{company_id}/owner_reportsCreate a portfolio owner report
  3. GET /rest/v1.0/companies/{company_id}/owner_reports/{id}Show an owner report
  4. PATCH /rest/v1.0/companies/{company_id}/owner_reports/{id}Update an owner report
  5. DELETE /rest/v1.0/companies/{company_id}/owner_reports/{id}Delete an owner report
  6. GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/pdfDownload a draft PDF
  7. GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/previewPreview the live report
  8. GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/share_linksList share links
  9. POST /rest/v1.0/companies/{company_id}/owner_reports/{id}/share_linksCreate an owner share link
  10. DELETE /rest/v1.0/companies/{company_id}/owner_reports/{id}/share_links/{link_id}Revoke a share link
  11. GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/share_links/{link_id}/viewsShare link access log
  12. GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/versionsList versions
  13. POST /rest/v1.0/companies/{company_id}/owner_reports/{id}/versionsPublish a version
  14. GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/versions/{version_id}Show a frozen version
  15. GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/versions/{version_id}/pdfDownload a frozen version's PDF
  16. GET /rest/v1.0/companies/{company_id}/owner_reports/ownersList owners for portfolio reports
  17. GET /rest/v1.0/projects/{project_id}/owner_reportsList owner reports
  18. POST /rest/v1.0/projects/{project_id}/owner_reportsCreate an owner report
  19. GET /rest/v1.0/projects/{project_id}/owner_reports/{id}Show an owner report
  20. PATCH /rest/v1.0/projects/{project_id}/owner_reports/{id}Update an owner report
  21. DELETE /rest/v1.0/projects/{project_id}/owner_reports/{id}Delete an owner report
  22. GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/pdfDownload a draft PDF
  23. GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/previewPreview the live report
  24. GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/share_linksList share links
  25. POST /rest/v1.0/projects/{project_id}/owner_reports/{id}/share_linksCreate an owner share link
  26. DELETE /rest/v1.0/projects/{project_id}/owner_reports/{id}/share_links/{link_id}Revoke a share link
  27. GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/share_links/{link_id}/viewsShare link access log
  28. GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/versionsList versions
  29. POST /rest/v1.0/projects/{project_id}/owner_reports/{id}/versionsPublish a version
  30. GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/versions/{version_id}Show a frozen version
  31. GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/versions/{version_id}/pdfDownload a frozen version's PDF
GET /rest/v1.0/companies/{company_id}/owner_reports

List portfolio owner reports

Portfolio reports belong to their creator and company administrators; each project inside is read with your access in that project.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • scope
    stringrequired
    One of: project, portfolio.
  • project_id
    integer | null
  • project_ids
    integer[]
    Portfolio reports: the projects included.
  • owner_vendor_id
    integer | null
  • template
    stringrequired
    One of: monthly_aia, gmp_cost, executive, portfolio.
  • template_name
    string
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sections
    string[]required
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.
  • content
    objectrequired
  • content.executive_summary
    string
  • content.section_notes
    object
    Commentary per section key.
  • content.risks
    object[]
  • content.lookahead_weeks
    integer
    One of: 2, 3, 6.
  • photo_ids
    integer[]required
  • created_by_id
    integer
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • latest_version
    object | null
  • latest_version.id
    integer
  • latest_version.version
    integer
  • latest_version.published_at
    string (date-time)
  • active_share_links
    integer | null

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/owner_reports" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/owner_reports

Create a portfolio owner report

Default period: the previous calendar month. Token scope: owner_reports:write.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • owner_report
    objectrequired
    Give owner_vendor_id, project_ids, or both (projects filtered to the owner).
  • owner_report.title
    string
  • owner_report.owner_vendor_id
    integer
  • owner_report.project_ids
    integer[]
  • owner_report.period_start
    string (date)
  • owner_report.period_end
    string (date)

Response · 201 · object

  • id
    integerrequired
  • scope
    stringrequired
    One of: project, portfolio.
  • project_id
    integer | null
  • project_ids
    integer[]
    Portfolio reports: the projects included.
  • owner_vendor_id
    integer | null
  • template
    stringrequired
    One of: monthly_aia, gmp_cost, executive, portfolio.
  • template_name
    string
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sections
    string[]required
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.
  • content
    objectrequired
  • content.executive_summary
    string
  • content.section_notes
    object
    Commentary per section key.
  • content.risks
    object[]
  • content.lookahead_weeks
    integer
    One of: 2, 3, 6.
  • photo_ids
    integer[]required
  • created_by_id
    integer
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • latest_version
    object | null
  • latest_version.id
    integer
  • latest_version.version
    integer
  • latest_version.published_at
    string (date-time)
  • active_share_links
    integer | null

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).
  • 422Validation failed.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/owner_reports" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "owner_report": {}
}'
GET /rest/v1.0/companies/{company_id}/owner_reports/{id}

Show an owner report

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • scope
    stringrequired
    One of: project, portfolio.
  • project_id
    integer | null
  • project_ids
    integer[]
    Portfolio reports: the projects included.
  • owner_vendor_id
    integer | null
  • template
    stringrequired
    One of: monthly_aia, gmp_cost, executive, portfolio.
  • template_name
    string
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sections
    string[]required
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.
  • content
    objectrequired
  • content.executive_summary
    string
  • content.section_notes
    object
    Commentary per section key.
  • content.risks
    object[]
  • content.lookahead_weeks
    integer
    One of: 2, 3, 6.
  • photo_ids
    integer[]required
  • created_by_id
    integer
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • latest_version
    object | null
  • latest_version.id
    integer
  • latest_version.version
    integer
  • latest_version.published_at
    string (date-time)
  • active_share_links
    integer | null

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/owner_reports/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/owner_reports/{id}

Update an owner report

Edit the narrative, section commentary, risks, sections, period and photo selection. Published versions are never changed.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • owner_report
    objectrequired
  • owner_report.title
    string
  • owner_report.period_start
    string (date)
  • owner_report.period_end
    string (date)
  • owner_report.sections
    string[]
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.
  • owner_report.content
    object
  • owner_report.content.executive_summary
    string
  • owner_report.content.section_notes
    object
    Commentary per section key.
  • owner_report.content.risks
    object[]
  • owner_report.content.risks[].title
    stringrequired
  • owner_report.content.risks[].impact
    stringrequired
    One of: low, medium, high.
  • owner_report.content.risks[].status
    stringrequired
    One of: open, monitoring, closed.
  • owner_report.content.risks[].owner
    stringrequired
  • owner_report.content.risks[].mitigation
    stringrequired
  • owner_report.content.lookahead_weeks
    integer
    One of: 2, 3, 6.
  • owner_report.photo_ids
    integer[]

Response · 200 · object

  • id
    integerrequired
  • scope
    stringrequired
    One of: project, portfolio.
  • project_id
    integer | null
  • project_ids
    integer[]
    Portfolio reports: the projects included.
  • owner_vendor_id
    integer | null
  • template
    stringrequired
    One of: monthly_aia, gmp_cost, executive, portfolio.
  • template_name
    string
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sections
    string[]required
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.
  • content
    objectrequired
  • content.executive_summary
    string
  • content.section_notes
    object
    Commentary per section key.
  • content.risks
    object[]
  • content.lookahead_weeks
    integer
    One of: 2, 3, 6.
  • photo_ids
    integer[]required
  • created_by_id
    integer
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • latest_version
    object | null
  • latest_version.id
    integer
  • latest_version.version
    integer
  • latest_version.published_at
    string (date-time)
  • active_share_links
    integer | null

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).
  • 422Validation failed.

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/owner_reports/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "owner_report": {}
}'
DELETE /rest/v1.0/companies/{company_id}/owner_reports/{id}

Delete an owner report

Soft-deletes the report and revokes its share links. Versions are kept.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/owner_reports/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/pdf

Download a draft PDF

Renders the live report as a branded PDF without publishing.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · string (binary)

No documented fields.

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/owner_reports/1/pdf" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/preview

Preview the live report

Assembles the report now from live project data with your access. Nothing is stored.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • document
    object
    The fully formatted report: every value is a display string. A denied source makes its section status unavailable (never zero).
  • document.v
    integerrequired
  • document.template
    stringrequired
  • document.title
    stringrequired
  • document.company
    objectrequired
  • document.project
    object | null
  • document.projects
    object[]
  • document.owner
    string | null
  • document.period
    objectrequired
  • document.preparedBy
    string
  • document.generatedAt
    string (date-time)
  • document.sections
    object[]required
  • sources
    string[]

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/owner_reports/1/preview" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/owner_reports/{id}/share_links

Create an owner share link

A read-only, expiring (max 90 days), revocable link to one published version, opened without a sign-in at /owner-report/{token}. Every open is logged. The token is returned once. Optionally emails the link.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • share_link
    objectrequired
  • share_link.version_id
    integerrequired
  • share_link.recipient_name
    string
  • share_link.recipient_email
    string (email)
  • share_link.expires_in_days
    integer
  • share_link.allow_pdf
    boolean
  • share_link.send_email
    boolean
    Email the link to recipient_email.

Response · 201 · object

  • id
    integerrequired
  • report_id
    integerrequired
  • version_id
    integerrequired
  • version
    integer | null
  • recipient_name
    string | null
  • recipient_email
    string | null
  • allow_pdf
    boolean
  • status
    stringrequired
    One of: active, expired, revoked.
  • expires_at
    string (date-time)required
  • revoked_at
    string | null
  • revoke_reason
    string | null
  • view_count
    integerrequired
  • last_viewed_at
    string | null
  • emailed_at
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)required
  • token
    string
    Only in the create response. The server keeps a hash; it cannot be shown again.
  • url
    string
    Only in the create response: the owner-facing link (/owner-report/{token}).
  • emailed
    boolean

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).
  • 422Validation failed or the version is not a published one.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/owner_reports/1/share_links" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "share_link": {
    "version_id": 1
  }
}'
GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/versions

List versions

Published versions and scheduled deliveries, newest first.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • report_id
    integerrequired
  • version
    integerrequired
  • kind
    stringrequired
    One of: published, scheduled.
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sources
    string[]required
    Tool slugs whose data the frozen version contains.
  • sha256
    stringrequired
    SHA-256 of the frozen PDF.
  • pdf_bytes
    integerrequired
  • photo_count
    integer
  • published_by
    object
  • published_by.id
    integer
  • published_by.name
    string | null
  • rendered_for
    object | null
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/owner_reports/1/versions" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/owner_reports/{id}/versions

Publish a version

Assembles the report with your access and freezes it (JSON, branded PDF and photo bytes, PDF SHA-256). Versions are immutable.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 201 · object

  • id
    integerrequired
  • report_id
    integerrequired
  • version
    integerrequired
  • kind
    stringrequired
    One of: published, scheduled.
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sources
    string[]required
    Tool slugs whose data the frozen version contains.
  • sha256
    stringrequired
    SHA-256 of the frozen PDF.
  • pdf_bytes
    integerrequired
  • photo_count
    integer
  • published_by
    object
  • published_by.id
    integer
  • published_by.name
    string | null
  • rendered_for
    object | null
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/owner_reports/1/versions" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/versions/{version_id}

Show a frozen version

Requires view on Owner Reports and on every source tool the version contains.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • version_id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • report_id
    integerrequired
  • version
    integerrequired
  • kind
    stringrequired
    One of: published, scheduled.
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sources
    string[]required
    Tool slugs whose data the frozen version contains.
  • sha256
    stringrequired
    SHA-256 of the frozen PDF.
  • pdf_bytes
    integerrequired
  • photo_count
    integer
  • published_by
    object
  • published_by.id
    integer
  • published_by.name
    string | null
  • rendered_for
    object | null
  • created_at
    string (date-time)required
  • document
    object
    The fully formatted report: every value is a display string. A denied source makes its section status unavailable (never zero).
  • document.v
    integerrequired
  • document.template
    stringrequired
  • document.title
    stringrequired
  • document.company
    objectrequired
  • document.project
    object | null
  • document.projects
    object[]
  • document.owner
    string | null
  • document.period
    objectrequired
  • document.preparedBy
    string
  • document.generatedAt
    string (date-time)
  • document.sections
    object[]required

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/owner_reports/1/versions/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/owner_reports/{id}/versions/{version_id}/pdf

Download a frozen version's PDF

Served only when its SHA-256 still matches (409 otherwise).

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • version_id
    integerpathrequired

Response · 200 · string (binary)

No documented fields.

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).
  • 409Integrity check failed.

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/owner_reports/1/versions/1/pdf" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/owner_reports/owners

List owners for portfolio reports

Owners (vendors on prime contracts) with the projects where you can view Owner Reports.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object[]

  • id
    integer
  • name
    string
  • projects
    object[]
  • projects[].id
    integer
  • projects[].name
    string

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/owner_reports/owners" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/projects/{project_id}/owner_reports

List owner reports

Owner Reports tool permission (view to read; create, edit or delete to change). Data sections are assembled with your access in each source tool.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • scope
    stringrequired
    One of: project, portfolio.
  • project_id
    integer | null
  • project_ids
    integer[]
    Portfolio reports: the projects included.
  • owner_vendor_id
    integer | null
  • template
    stringrequired
    One of: monthly_aia, gmp_cost, executive, portfolio.
  • template_name
    string
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sections
    string[]required
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.
  • content
    objectrequired
  • content.executive_summary
    string
  • content.section_notes
    object
    Commentary per section key.
  • content.risks
    object[]
  • content.lookahead_weeks
    integer
    One of: 2, 3, 6.
  • photo_ids
    integer[]required
  • created_by_id
    integer
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • latest_version
    object | null
  • latest_version.id
    integer
  • latest_version.version
    integer
  • latest_version.published_at
    string (date-time)
  • active_share_links
    integer | null

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/owner_reports" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/projects/{project_id}/owner_reports

Create an owner report

Default period: the previous calendar month. Templates: monthly_aia (AIA-style monthly report), gmp_cost (cost-plus backup summary), executive (one-pager).

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • owner_report
    objectrequired
  • owner_report.template
    stringrequired
    One of: monthly_aia, gmp_cost, executive.
  • owner_report.title
    string
  • owner_report.period_start
    string (date)
  • owner_report.period_end
    string (date)
  • owner_report.sections
    string[]
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.

Response · 201 · object

  • id
    integerrequired
  • scope
    stringrequired
    One of: project, portfolio.
  • project_id
    integer | null
  • project_ids
    integer[]
    Portfolio reports: the projects included.
  • owner_vendor_id
    integer | null
  • template
    stringrequired
    One of: monthly_aia, gmp_cost, executive, portfolio.
  • template_name
    string
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sections
    string[]required
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.
  • content
    objectrequired
  • content.executive_summary
    string
  • content.section_notes
    object
    Commentary per section key.
  • content.risks
    object[]
  • content.lookahead_weeks
    integer
    One of: 2, 3, 6.
  • photo_ids
    integer[]required
  • created_by_id
    integer
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • latest_version
    object | null
  • latest_version.id
    integer
  • latest_version.version
    integer
  • latest_version.published_at
    string (date-time)
  • active_share_links
    integer | null

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).
  • 422Validation failed.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/owner_reports" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "owner_report": {
    "template": "monthly_aia"
  }
}'
GET /rest/v1.0/projects/{project_id}/owner_reports/{id}

Show an owner report

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • scope
    stringrequired
    One of: project, portfolio.
  • project_id
    integer | null
  • project_ids
    integer[]
    Portfolio reports: the projects included.
  • owner_vendor_id
    integer | null
  • template
    stringrequired
    One of: monthly_aia, gmp_cost, executive, portfolio.
  • template_name
    string
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sections
    string[]required
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.
  • content
    objectrequired
  • content.executive_summary
    string
  • content.section_notes
    object
    Commentary per section key.
  • content.risks
    object[]
  • content.lookahead_weeks
    integer
    One of: 2, 3, 6.
  • photo_ids
    integer[]required
  • created_by_id
    integer
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • latest_version
    object | null
  • latest_version.id
    integer
  • latest_version.version
    integer
  • latest_version.published_at
    string (date-time)
  • active_share_links
    integer | null

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/owner_reports/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/projects/{project_id}/owner_reports/{id}

Update an owner report

Edit the narrative, section commentary, risks, sections, period and photo selection. Published versions are never changed.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • owner_report
    objectrequired
  • owner_report.title
    string
  • owner_report.period_start
    string (date)
  • owner_report.period_end
    string (date)
  • owner_report.sections
    string[]
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.
  • owner_report.content
    object
  • owner_report.content.executive_summary
    string
  • owner_report.content.section_notes
    object
    Commentary per section key.
  • owner_report.content.risks
    object[]
  • owner_report.content.risks[].title
    stringrequired
  • owner_report.content.risks[].impact
    stringrequired
    One of: low, medium, high.
  • owner_report.content.risks[].status
    stringrequired
    One of: open, monitoring, closed.
  • owner_report.content.risks[].owner
    stringrequired
  • owner_report.content.risks[].mitigation
    stringrequired
  • owner_report.content.lookahead_weeks
    integer
    One of: 2, 3, 6.
  • owner_report.photo_ids
    integer[]

Response · 200 · object

  • id
    integerrequired
  • scope
    stringrequired
    One of: project, portfolio.
  • project_id
    integer | null
  • project_ids
    integer[]
    Portfolio reports: the projects included.
  • owner_vendor_id
    integer | null
  • template
    stringrequired
    One of: monthly_aia, gmp_cost, executive, portfolio.
  • template_name
    string
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sections
    string[]required
    One of: executive_summary, budget_gmp, contingency_allowances, billing, change_orders, schedule, lookahead, rfis_submittals, safety, quality, photos, risks, compliance.
  • content
    objectrequired
  • content.executive_summary
    string
  • content.section_notes
    object
    Commentary per section key.
  • content.risks
    object[]
  • content.lookahead_weeks
    integer
    One of: 2, 3, 6.
  • photo_ids
    integer[]required
  • created_by_id
    integer
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • latest_version
    object | null
  • latest_version.id
    integer
  • latest_version.version
    integer
  • latest_version.published_at
    string (date-time)
  • active_share_links
    integer | null

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).
  • 422Validation failed.

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/projects/1/owner_reports/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "owner_report": {}
}'
DELETE /rest/v1.0/projects/{project_id}/owner_reports/{id}

Delete an owner report

Soft-deletes the report and revokes its share links. Versions are kept.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/projects/1/owner_reports/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/pdf

Download a draft PDF

Renders the live report as a branded PDF without publishing.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · string (binary)

No documented fields.

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/owner_reports/1/pdf" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/preview

Preview the live report

Assembles the report now from live project data with your access. Nothing is stored.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • document
    object
    The fully formatted report: every value is a display string. A denied source makes its section status unavailable (never zero).
  • document.v
    integerrequired
  • document.template
    stringrequired
  • document.title
    stringrequired
  • document.company
    objectrequired
  • document.project
    object | null
  • document.projects
    object[]
  • document.owner
    string | null
  • document.period
    objectrequired
  • document.preparedBy
    string
  • document.generatedAt
    string (date-time)
  • document.sections
    object[]required
  • sources
    string[]

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/owner_reports/1/preview" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/projects/{project_id}/owner_reports/{id}/share_links

Create an owner share link

A read-only, expiring (max 90 days), revocable link to one published version, opened without a sign-in at /owner-report/{token}. Every open is logged. The token is returned once. Optionally emails the link.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • share_link
    objectrequired
  • share_link.version_id
    integerrequired
  • share_link.recipient_name
    string
  • share_link.recipient_email
    string (email)
  • share_link.expires_in_days
    integer
  • share_link.allow_pdf
    boolean
  • share_link.send_email
    boolean
    Email the link to recipient_email.

Response · 201 · object

  • id
    integerrequired
  • report_id
    integerrequired
  • version_id
    integerrequired
  • version
    integer | null
  • recipient_name
    string | null
  • recipient_email
    string | null
  • allow_pdf
    boolean
  • status
    stringrequired
    One of: active, expired, revoked.
  • expires_at
    string (date-time)required
  • revoked_at
    string | null
  • revoke_reason
    string | null
  • view_count
    integerrequired
  • last_viewed_at
    string | null
  • emailed_at
    string | null
  • created_by_id
    integer
  • created_at
    string (date-time)required
  • token
    string
    Only in the create response. The server keeps a hash; it cannot be shown again.
  • url
    string
    Only in the create response: the owner-facing link (/owner-report/{token}).
  • emailed
    boolean

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).
  • 422Validation failed or the version is not a published one.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/owner_reports/1/share_links" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "share_link": {
    "version_id": 1
  }
}'
GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/versions

List versions

Published versions and scheduled deliveries, newest first.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • report_id
    integerrequired
  • version
    integerrequired
  • kind
    stringrequired
    One of: published, scheduled.
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sources
    string[]required
    Tool slugs whose data the frozen version contains.
  • sha256
    stringrequired
    SHA-256 of the frozen PDF.
  • pdf_bytes
    integerrequired
  • photo_count
    integer
  • published_by
    object
  • published_by.id
    integer
  • published_by.name
    string | null
  • rendered_for
    object | null
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/owner_reports/1/versions" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/projects/{project_id}/owner_reports/{id}/versions

Publish a version

Assembles the report with your access and freezes it (JSON, branded PDF and photo bytes, PDF SHA-256). Versions are immutable.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 201 · object

  • id
    integerrequired
  • report_id
    integerrequired
  • version
    integerrequired
  • kind
    stringrequired
    One of: published, scheduled.
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sources
    string[]required
    Tool slugs whose data the frozen version contains.
  • sha256
    stringrequired
    SHA-256 of the frozen PDF.
  • pdf_bytes
    integerrequired
  • photo_count
    integer
  • published_by
    object
  • published_by.id
    integer
  • published_by.name
    string | null
  • rendered_for
    object | null
  • created_at
    string (date-time)required

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/owner_reports/1/versions" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/versions/{version_id}

Show a frozen version

Requires view on Owner Reports and on every source tool the version contains.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • version_id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • report_id
    integerrequired
  • version
    integerrequired
  • kind
    stringrequired
    One of: published, scheduled.
  • title
    stringrequired
  • period_start
    string (date)required
  • period_end
    string (date)required
  • sources
    string[]required
    Tool slugs whose data the frozen version contains.
  • sha256
    stringrequired
    SHA-256 of the frozen PDF.
  • pdf_bytes
    integerrequired
  • photo_count
    integer
  • published_by
    object
  • published_by.id
    integer
  • published_by.name
    string | null
  • rendered_for
    object | null
  • created_at
    string (date-time)required
  • document
    object
    The fully formatted report: every value is a display string. A denied source makes its section status unavailable (never zero).
  • document.v
    integerrequired
  • document.template
    stringrequired
  • document.title
    stringrequired
  • document.company
    objectrequired
  • document.project
    object | null
  • document.projects
    object[]
  • document.owner
    string | null
  • document.period
    objectrequired
  • document.preparedBy
    string
  • document.generatedAt
    string (date-time)
  • document.sections
    object[]required

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/owner_reports/1/versions/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/projects/{project_id}/owner_reports/{id}/versions/{version_id}/pdf

Download a frozen version's PDF

Served only when its SHA-256 still matches (409 otherwise).

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • version_id
    integerpathrequired

Response · 200 · string (binary)

No documented fields.

Errors

  • 401Missing or invalid credentials.
  • 403No permission, tool disabled, or token lacks the scope.
  • 404Not found (or not visible to you).
  • 409Integrity check failed.

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/owner_reports/1/versions/1/pdf" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file