Esc

↑↓ move↵ openIndex · Pagefind

Schedule API workflow

Keep saved plans, calculated results and field-task changes separate. The Schedule API provides explicit review boundaries before existing task dates change.

Explicit publication workflows. Adopted-import projection updates eligible linked task dates. Native publication reviews supported unstarted activities; the separate hierarchy workflow adds WBS summaries and parent changes. Saving a plan never applies it automatically. Progressed work and mixed-source reconciliation remain unsupported. Control and endpoint availability depend on the deployed app version.

Calculate and analyse a saved schedule

POST /calculations runs the P6-validated CPM engine on the project's current head version and retains an immutable result. Send expected_version_id (the current head; a stale value returns 409) and an operation:

OperationExtra fieldsResult
scheduleoptional data_dateEarly and late dates, total and free float, critical and longest-path flags, the ordered longest_path, driving_set, driving predecessors and a per-activity explainability object.
healthoptional data_dateDCMA 14-point checks: grade, score, pass/fail/skipped counts and a checks list with value, threshold, threshold source, detail and up to 20 offenders. Always publish the basis text with the grade.
riskrisk.iterations (100–20,000, default 2,000), risk.distribution (pert or triangular), risk.seed (default 12345; null generates a seed and records it)Monte Carlo percentiles P10–P95, an s_curve from P5 to P95, the deterministic finish and the confidence of meeting it, and up to 15 drivers with criticality index and duration sensitivity. Three-point estimates, risk events, correlation groups and key dates are read from the saved version's risk model, and the result records the estimates source, seed and model digests.
earnedrequired baseline_version_id, optional data_dateEarned Schedule in working days: planned duration, actual time, earned days and spi_t. Compute SPI(t) as earned_days / actual_time_days.
comparerequired baseline_version_id; data_date is rejectedFinish movement in calendar days with an explanation, criticality gained and lost, the match key, and per-activity date and float deltas with change kinds.

baseline_version_id is a saved schedule version in the same project, such as a named baseline's version_id. The other operations reject it, and risk options are accepted only for risk. Calculations require Schedule admin and schedule:write, because full-network results can disclose private activities. Responses are private, no-store. The reference documents every result field. The in-app API docs show a request and response example for each operation.

curl -X POST "$APP/rest/v1.0/projects/2/schedule/calculations" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"expected_version_id": 42, "operation": "earned", "baseline_version_id": 17}'

For the product view of these results, see Schedule analysis and Risk analysis. There is no separate endpoint for editing risk inputs: they are part of the saved definition, edited in the app's Risk page.

Read the schedule log of a calculation

Every schedule calculation stores a schedule log. GET /calculations/{id}/log returns it for the calculation id (a schedule operation in this project). The log covers the options used, the critical path definition with critical and longest-path counts, and five sections of findings: open_ends, constraints, out_of_sequence, missing_actual_start and actuals_after_data_date. Each section has a full count and up to 2,000 entries, with truncated set when there are more. An entry carries dcma_check (1, 5 or 9) when the DCMA health check names the same activity.

The only query parameter is format: json (the default), text or csv; the last two download as attachments. The JSON wrapper includes calculation_id, version_id, version, created_at and stored. Calculations saved before the log existed return a log rebuilt from the saved version and result, with stored: false; if that version fails its integrity check, the request returns 409. The log requires schedule:read and live Schedule admin permission, and responses are private, no-store. Reading it never recalculates.

Background analysis jobs

Long analyses run as background jobs on their own engine lane. POST /calculations decides for you: a risk run stays inline while activities × iterations is at most 500,000, and queues above that. Forensic reports, scenario calculation and compression, and leveling resource reports queue when their estimate passes about 10 seconds. Add ?async=1 or Prefer: respond-async to force a job, which returns 202 with a Location header; ?async=0 forces an inline run with a 30-second limit.

OperationBehaviour
GET /analysis-jobsList jobs. Filter by kind (calculation, forensic, scenario_calculate, scenario_compression, resource_report), active and scenario_id; page with before_id and page_size.
GET /analysis-jobs/{job_id}Status (queued, running, completed, failed, cancelled), progress 0–100 and, when complete, its result.
POST /analysis-jobs/{job_id}/cancelStop the engine run. Requires schedule:write.

A job's time budget is twice its estimate, at least 2 minutes and at most 2 hours by default; requests estimated above the ceiling return 422. An identical request already running for the same user returns that job rather than a new one. Pinned versions are rechecked before the run, and a changed version fails the job with 409. Only an engine-busy or engine-unavailable failure before the result is saved is retried, up to 3 attempts. Jobs require Schedule admin.

Export a version to P6 or MSPDI

GET /versions/{version_id}/export?format=xer|p6xml|mspdi recalculates a saved version (use current for the head) and returns it as P6 XER, P6 XML or MSPDI, with retained P6 metadata restored and your edits winning over it. Responses are private, no-store, with X-Schedule-Export-SHA256, X-Schedule-Version-ID and X-Schedule-Export-Issues headers. Export requires Schedule admin because the file discloses the whole network; nothing is written. GET /exports/{import_id} still returns the original uploaded bytes. Imports accept UTF-8 sources up to 32 MiB and plans up to 30,000 activities. See P6 compatibility for what round-trips.

Update the current plan from an import

P6 import options. The retained XER, P6 XML or MSPDI source of a schedule import, previewed or imported, is read by the engine and merged into the project's current plan. Both operations need live Schedule admin; tokens need schedule:write. Send expected_version_id (the current head; 409 when it moved).

OperationBehaviour
POST /imports/{import_id}/merge/previewReview the merge. mode is update (Update existing plan), replace or add_to_wbs (with target_wbs_id, an existing WBS node). For update, an optional template sets an action per object type (activities, relationships, wbs, calendars, codes, udfs, resources, assignments, notebooks, settings): update_existing, insert_new, keep_existing or delete_existing. Notebooks and settings take only the first and third. Returns the effective template, per-type counts, a summary, up to 50 activity changes in sample with field-level before and after, renamed identities, warnings, activity_count and a preview_digest. Nothing is written.
POST /imports/{import_id}/merge/applyThe same body plus the preview_digest. Saves one new version through the versioned save path, calculates it and records an audit event. Returns 201 with version, calculation_id, counts and summary. 409 when there's no current plan, the plan or the preview changed, or the retained source fails its integrity check.

Activities match by retained P6 GUID, else by Activity ID, and matched objects keep their local identity. Objects the result still uses are never deleted. An engine-busy source read returns 429 with Retry-After, and an unavailable engine 503. See Update the current plan from a file.

Activity spreadsheet round-trip

Export the current version's activity table to XLSX, edit it, and apply it back as a reviewed update. All three operations need live Schedule admin; the export needs schedule:read and the writes schedule:write.

OperationBehaviour
GET /spreadsheetAn XLSX workbook with one row per activity: Activity ID (the match key), Activity Name, then a layout's visible columns, codes and UDFs included. Choose the columns with layout_ref (builtin:classic or layout:{id}) or a comma-separated columns list such as duration,start,code:Area,udf:Inspector. A Columns sheet records each header's key and whether it's editable. The X-Schedule-Version-ID header names the version exported.
POST /spreadsheet/previewSend expected_version_id, the edited workbook as file_base64 (at most 1.5 MiB decoded) and unknown_ids (reject, the default, or insert). Every edited cell is validated like an inline grid edit. Returns matched rows, cell changes with before and after, rejected cells with reasons (edited calculated columns, invalid values, duplicate IDs), ignored_columns, inserted and rejected IDs, and a preview_digest.
POST /spreadsheet/applyThe same body plus the preview_digest. Saves one new version, calculates it and records an audit event. Returns 201 with version, calculation_id, changes_total, inserted and rejected_total. 409 when the plan or the preview changed.

Requests over 2 MiB return 413, and bodies that aren't application/json return 415. See Round-trip the activity table through Excel.

Planner layouts

Layouts are stored on the server at three scopes: user (Mine), project and shared (company-wide). Reads need schedule:read; writes need schedule:write.

OperationBehaviour
GET /layoutsBuilt-in, project, shared and personal layouts, your default, the project default and which scopes you can save to.
POST /layoutsCreate a layout with scope, name (1–80 characters, unique per scope), document (at most 256 KiB) and optional set_default. Project scope needs Schedule admin; shared scope needs company admin plus Schedule admin.
PATCH /layouts/{layout_id}, DELETE /layouts/{layout_id}Rename or re-save with the revision you read (a stale revision returns 409), or delete. Only the owner can change a personal layout.
PUT /layout-defaultsSet target user or project to a layout_ref, or null to clear. A personal layout can't be the project default.
POST /layout-importsCopy up to 20 browser-stored views into your personal scope. Names already used there are skipped.

Each scope holds up to 200 layouts. A layout document carries columns, widths and title overrides, filters, Group & Sort, sort keys, Gantt options including the progress line, display mode, the Assignments view and Resource Usage setup, the Activity Details tab setup and Trace Logic levels. See Views and layouts.

Layout files

OperationBehaviour
GET /layout-filesDownload a built-in or visible layout, named by the required layout_ref, as an attachment: an envelope with format "os.construction layout", version 1, name and document. Importing the file back is lossless. Needs schedule:read.
POST /layout-filesImport a file as a new layout. Send file (the file text: an envelope or a bare layout document, at most 260 KiB), optional file_name, scope (user, the default, project or shared, with the same permissions as creating a layout), optional name (a taken name gets a numbered suffix) and set_default. The file is validated by the stored-layout readers; issues lists parts that were reset. Returns 201 with the layout. A P6 .plf file is refused with 400 and an explanation, because its format isn't publicly documented. 409 when the scope is full. Needs schedule:write.

Update periods and schedule submittals

Every update and submittal operation requires live Schedule admin; reads need schedule:read and writes schedule:write. Writes that change an update send its expected_revision, and creates send a request_id (UUID) so a retry can't open two periods or build two packages.

OperationBehaviour
GET /updates, POST /updatesPage through update periods by status (open, submitted, revision_requested, approved, withdrawn), or open one with expected_version_id, a new data_date, optional name and baseline_id. Only one update can be in progress per project.
GET /updates/{update_id}, PATCH /updates/{update_id}Read the update, or edit its name and the six narrative sections (critical_path, progress, delays, changes, risks, mitigation; up to 20,000 characters each).
POST /updates/{update_id}/checksRun the eight update checks and store the evidence with a digest. Returns 201 with a check run.
POST /updates/{update_id}/submitSubmit with the latest check_run_id on an unchanged plan. Failed checks need acknowledge_failures: true. Name up to 25 reviewers (user_id, workflow_group_number, step_type Approver or Reviewer) or a workflow_template_id; at least one approver is required.
GET /updates/{update_id}/reviewCompare a submission with the previous accepted update, or the baseline for the first update.
POST /updates/{update_id}/respondapproved, approved_as_noted or revise_and_resubmit (which needs a comment). The final approval makes the update of record, which can't be changed afterwards. Submitters can't respond to their own submission.
POST /updates/{update_id}/comments, POST /updates/{update_id}/comments/{comment_id}/resolveComment on a submitted update, optionally on an activity_id (up to 4,000 characters), and resolve comments.
POST /updates/{update_id}/withdrawWithdraw an update that isn't approved, with a reason.
GET /submittals, POST /submittalsList packages, or build one for subject update (with period_id and optional submission_id) or baseline (with baseline_id), in formats xer and/or p6xml, with an optional cover_note.
GET /submittals/{submittal_id}, GET /submittals/{submittal_id}/files/{kind}Read a package or download one of its immutable files: xer, p6xml, narrative, health or compare.
POST /submittals/{submittal_id}/distributeSend the package once, by email, to project users (to, cc) and external addresses (to_external, cc_external), up to 50 each.
POST /submittals/{submittal_id}/responseRecord the reviewer's response (approved, approved_as_noted, revise_and_resubmit or rejected) and response_date once.

See The update cycle and review.

Prospective time impact analyses

A prospective TIA (AACE RP 52R-06) is a reviewed record: a fragnet is submitted, reviewed and accepted or rejected by another Schedule admin, and only an accepted fragnet is analysed. Every operation needs live Schedule admin; reads need schedule:read and writes schedule:write. Linking a change event also needs edit access to it.

OperationBehaviour
GET /time-impact-analyses, POST /time-impact-analysesList analyses, filtered by change_event_id and status (submitted, reviewed, accepted, rejected) and paged with before_id and page_size (1–100). Or submit one: title, delay_start, unit (work_days or calendar_days), optional change_event_id, a fragnet (id, description, narrative, up to 200 events each with duration_days and the activity it impacts, plus extra_links), optional already_awarded dates, mitigation fields and a request_id (UUID; a retry returns 200 with replayed). The fragnet goes into the update in effect: the last approved update period statused on or before delay_start. Refused when none qualifies or the fragnet names activities not in it.
GET /time-impact-analyses/{id}One analysis with its status, history and linked report.
POST /time-impact-analyses/{id}/review, POST /time-impact-analyses/{id}/decisionRecord the owner's review note (submitted to reviewed), then the decision accepted or rejected (a rejection needs a note). Both send expected_revision, and neither can be made by the submitter.
POST /time-impact-analyses/{id}/analyzeRun RP 52R-06 Steps 2–8 on an accepted fragnet and the later approved updates, keeping an immutable forensic report linked to the analysis. Large networks run as a background job (?async=1 or Prefer: respond-async, 202). A refusal by the standard returns its category and keeps nothing.

Submitted inputs are fixed by the database, review and decision are final, and every transition is audited on the analysis and the linked change event. MIP 3.5 (modified_or_recreated, with a provenance and modification register per update) and pacing claims on concurrency run through the existing forensic analysis operation. See Prospective time impact analysis.

Template library and lessons learned

OperationBehaviour
GET /library/templates, POST /library/templatesList the company templates and your private ones, optionally by kind (plan or fragment) and with include_archived=true. Or save one from this project's plan: name, optional description, sector, visibility (private or company) and note, and a selection whose kind is plan, or fragment with wbs_ids and/or activity_ids.
GET /library/templates/{template_id}, PATCH /library/templates/{template_id}Read a template with its versions and content (?version= for an earlier one), or change its name, description, sector, visibility or archived. Changes need the owner, or a company admin for a company template.
POST /library/templates/{template_id}/versionsAdd a new version from this project's plan with a selection and optional note. Earlier versions are kept.
POST /library/templates/{template_id}/insertInsert a fragment into this project's plan with expected_version_id (409 when stale), optional version, parent_wbs_id, predecessor_id, successor_id, an ID prefix, and optional lessons to scale durations. Saves a new version.
GET /lessons-learnedActual against planned working days of completed activities across the projects where the caller is Schedule admin, grouped by group_by name (default), trade or code (with code_type), from scope completed_projects or completed_activities, keeping groups with at least min_samples (default 3). Each group reports samples, projects, median planned and actual days and the P20, median and P80 ratio.

Reads need schedule:read and any Schedule access; saving, versions and inserting need schedule:write and Schedule admin on the project. Creating a new plan from a company template is an app action. See Company template library.

Reports, print Gantt and the assistant

OperationBehaviour
GET /reportsThe report catalog with each report's title and description.
GET /reports/{report_key}Build one of twelve reports (critical_path, total_float, lookahead, baseline_variance, milestones, period_progress, out_of_sequence, constraints, open_ends, resource_usage, cost_evm, dcma_health) as json, csv, xlsx or pdf. Options: weeks (2, 3 or 6), from/to, baseline_id, paper and orientation. cost_evm also needs budget:read and Budget view.
GET /baseline-assignments, PUT /baseline-assignmentsRead or set the shared project_baseline_id and the caller's own primary_baseline_id, secondary_baseline_id and tertiary_baseline_id (each nullable; send at least one). The response's effective slots show the primary falling back to the project baseline. Project baseline changes are audited. Assignments are view choices and never change a schedule or baseline. Requires Schedule admin.
GET /gantt-printA vector Gantt PDF of the saved schedule. Pass layout (a Planner layout reference) to use that layout's timescale, Bar Chart Options and bar list, including baseline bars. Other options: paper (default tabloid), orientation, timescale (day, week, month, quarter), fit (none tiles pages, width, page), filter (all, critical, incomplete), columns, show_baseline, baseline_id, show_legend, from, to and title. At most 400 pages.
GET /assistant, POST /assistantCheck whether the assistant is available, then ask a question (3–1,000 characters) with mode answer or narrative. Answers cite numbered facts from saved schedule data; uncited answers are flagged. The assistant never writes to the schedule. It is off unless enabled for the deployment and the company, and is rate-limited per user (30 questions an hour by default; 429 beyond that).

All four need schedule:read and Schedule admin. Recurring email delivery of a report or the print Gantt (daily, weekly or monthly, as PDF, XLSX or CSV) is set up in the app's Reports page; recipients are re-authorized at every send. Reports and prints read stored data only and say when an input is unavailable rather than returning zero. See Reports and printing.

Activity links tie records in other tools to schedule activities. GET /links filters by source_type, source_id and activity_id. POST /links creates one with source_type (submittal, purchase_order or material_delivery gate an activity; rfi, inspection or punch_item block it; manpower_log, notes_log or quantity_log report progress), source_id, activity_id, and optional lead_time_days, forecast_date, progress_event, progress_percent and note. Change-event links are created through change-event impacts. PATCH /links/{link_id} accepts an optional expected_updated_at: if the link changed since you read it, the update returns 409. POST /links/alerts evaluates link alerts and sends notifications.

Documents and drawings link as references (Activity Details WPs & Docs): source_type document or drawing, with workflow reference. A reference never gates, blocks or evidences progress. Creating or removing one needs Schedule edit and view access to Documents or Drawings, and a document is visible only under its folder and file grants. GET /links filters by both types like any other.

Line of Balance and takt plans

OperationBehaviour
GET /line-of-balanceThe location breakdown (its source: code, project or field, nodes in flow order, and how many activities are placed), the flowline of the saved head version's latest calculation (one line per trade with segments per location, rate per week and waiting days), conflicts, buffers (tight under min_buffer_days, 0–365) and crossings, and the zone-by-zone adherence of every generated takt plan. depth (0–20) rolls placements up to a hierarchy level. line_of_balance is null until the head has a calculation. Activities without a location, trade or dates are counted in skipped, and findings stop at 1,000 of each kind (truncated). Read only; nothing is rescheduled.
POST /takt/previewPlans a takt train with the engine's takt module: takt_days (1–60), start, zones (up to 200, in flow order), wagons (trades in handover order, up to 60, each with work_content per zone or default_work in crew-days, and max_crews 1–50) and an optional calendar of working weekdays and holidays; at most 6,000 zone × trade slots. Returns slot rows, crews, utilisation, overloaded trades, buildable, the minimum_takt and the network (tasks pinned start-on-or-after their takt, and finish-to-start links). Nothing is stored. 422 when the engine rejects the inputs, 429 when calculation capacity is busy.

Both need schedule:read and Schedule admin, because they expose the full network. A preview reaches a plan only through the Planner, as one reviewed draft edit, or through your own versioned save of a definition with the generated activities. See Location-based planning.

Weekly work plans and PPC

OperationBehaviour
GET /weekly-plans, POST /weekly-plansList plans in a window of weeks (from, to, weeks 1–104, default the 12 weeks to the current week), newest first, each with its commitments and week PPC; or start the draft plan for a Monday week_starting with an optional note. One plan per week (409 when it exists).
GET /weekly-plans/{plan_id}, PATCH, DELETERead one plan, change its note, or delete it. Only a draft week can be deleted.
POST /weekly-plans/{plan_id}/commitFreeze the week's commitments. Refused (409) with no commitments, or while any commitment's activity has open constraints in that week's constraints lookahead, unless allow_constrained: true, which is recorded on the plan and in the audit trail. Refused (422) when a commitment names an activity removed from the schedule since it was added.
POST /weekly-plans/{plan_id}/commitmentsAdd one commitment (activity_id, description, optional trade, planned_quantity, unit and notes) or a batch of up to 200 (commitments) to a draft week. A week holds up to 500. Each activity_id must be an activity of the project's current saved schedule that you can see, or 422. A week that has ended may also name an activity of the schedule as it stood that week. An omitted trade is filled from the activity's trade field or trade activity code; 422 when it has neither.
PATCH /weekly-plans/{plan_id}/commitments/{commitment_id}, DELETEOn a draft week, rewrite or remove the promise; a new activity_id is checked as when adding. On a committed week, only assess it: completed: true, completed: false with a variance_reason (prerequisite_work, materials, labour, equipment, information, design_change, directive, weather, access, over_commitment or not_recorded), or completed: null; notes may change.
GET /ppcEvery week of a window (from, to, weeks), with unplanned weeks as none; the mean PPC over measurable weeks only; per-trade PPC; missed commitments by reason with the top three; and issues about the measurement (an empty committed week, unassessed commitments, unexplained misses).

Reads need schedule:read and Schedule view; writes need schedule:write and Schedule edit. PPC is null for a week with any unassessed commitment or with none, never 0 or 100. The database also refuses changes to a committed week's commitments. Every write is audited, and nothing moves a schedule date. A committed week's commitments are never re-checked against the schedule, so they stay assessable after their activity is removed. See Last Planner.

Activity discussion, presence and the change feed

OperationBehaviour
GET /activity-comments, POST /activity-commentsList threads, optionally for one activity_id and by status (open, resolved, all), with open, resolved and total counts. Create a thread on an activity of the saved head (activity_id, body up to 5,000 characters, optional private) or a reply (parent_id; it inherits the thread's activity and privacy). @Full Name or @email mentions (up to 20) notify, in the app and by email preference, only people who currently have Schedule access to the activity; a reply also notifies earlier participants. A private comment is visible to its author only and notifies nobody.
PATCH /activity-comments/{comment_id}, DELETEEdit your own comment's body (only newly mentioned people are notified), or set resolved on a thread root. Delete your own comment (Schedule admins: any); it keeps its place with no text. 409 when it was deleted or changed concurrently.
GET /activity-comments/counts, GET /activity-comments/mentionableOpen threads, resolved threads and comments per activity; and the people a mention can reach, narrowed to those who can see activity_id when given.
GET /presence, POST /presence, DELETE /presence?session_id=Who else has the Planner open (seen within ttl_ms, 45 seconds), one entry per person with their selected activity and whether they hold unsaved edits to it, plus the saved head. POST is a heartbeat for one session_id with activity_id, editing and version_id; poll about every 15 seconds. DELETE ends a session. Advisory only: presence never blocks a save. Activities you can't see are reported as hidden.
GET /feedNewest first: saved versions with a cached change summary, recalculations, baselines, update-cycle events, adopted scenarios, imports and discussion. Filter by kinds (comma-separated version, calculation, baseline, update, scenario, import, comment) or activity_id (discussion only), with limit 1–100 and before = the previous next_cursor. Up to three uncached summaries are computed per request; the rest read as pending.
GET /feed/changesEvery changed activity of one version change, a page at a time: version_id, optional against_version_id (default: the version it replaced), offset and limit (up to 200). Feed and banner summaries name only the first 25; this pages through all of them. Summaries of versions saved after this release are stored at save time, so the feed reads them directly. Needs Schedule admin.
GET /feed/since, POST /feed/seenWhat changed since you last acknowledged a version: the versions saved since (up to 50), one combined change summary naming up to 25 activities, and comments by others. The first call records the head and reports nothing (first_visit). POST acknowledges a version_id.

All need Schedule access on an active project with the tool on. Reads and presence need schedule:read and Schedule view, and comment writes need schedule:write and Schedule edit. Non-admins only see discussion on activities bound to a field task they can see, and the feed shows them discussion only (full_network: false). /feed/since and /feed/seen need Schedule admin. Comment changes are audited without their text. Rebasing unsaved edits after a 409 happens in the Planner; over the API, re-read the head and save again with its expected_version_id. See Working together on a schedule.

Cost loading

GET /cost-mappings reads the revisioned mapping set that spreads Budget lines over activities; PUT /cost-mappings replaces it with expected_revision (409 on a stale revision), a list of mappings (source_type, activity_id, budget_line_id, allocation_basis_points) and an optional reason. GET /cost-dashboard returns cost-loaded earned value, S-curves, a cash-flow forecast and mapping exceptions, with optional baseline_id and bucket (month or week); The dashboard also carries an expenses block for P6 activity expenses (totals, per cost account, per activity and phased by accrual type, plus undated_activity_ids), reported beside the budget at completion and never inside it (basis: schedule_expenses_not_in_bac). GET /cost-dashboard/csv exports both. The dashboard also reports earned_value_options, each activity's performance_percent_complete, and an expense_reconciliation per cost code. These need budget:read as well as the schedule scope.

Cost account mappings

GET /cost-account-mappings reads the revisioned set that maps P6 cost accounts (on expenses and assignments) to the project's cost codes, with each account's usage in the current schedule; ?revision= reads an earlier revision. PUT /cost-account-mappings saves the complete set as the next revision: expected_revision (409 when stale), up to 5,000 mappings (account_id or account_name, and cost_code_id; one cost code per account) and an optional reason. Rows are immutable, every save is audited with what was added, removed and changed, and an unmapped account inherits its nearest mapped parent. Nothing is posted to the Budget or the ledger. Reads need schedule:read, saves schedule:write, both with budget:read, Schedule admin and Budget view. See Resources and costs.

Financial periods, period performance and earned value

Every operation needs live Schedule admin on the project, with schedule:read for reads and schedule:write for writes. Company-wide periods are created, renamed and deleted only by company admins. Amounts are exact two-decimal strings. Sources are schedule resource actuals: the Accounting ledger is never read or written, and store responses say so with ledger_writes: false.

OperationBehaviour
GET /financial-periodsCompany-wide and project periods in date order, each with this project's effective stored run (stored), and what the caller may manage.
POST /financial-periodsCreate one period (name up to 80 characters, start_date, end_date, scope project or company), a batch of up to 120 (periods), or copy an Accounting fiscal year as read-only company periods (source accounting with a fiscal_year; the adjusting period 13 is skipped). Periods of one scope can't overlap and span at most a year. Returns 201 with the updated list; 409 when that fiscal year was already copied.
PATCH /financial-periods/{period_id}, DELETE /financial-periods/{period_id}Rename a period (dates and scope are immutable), or delete it. A period with stored performance in any project is retained (409). Audited.
POST /financial-periods/{period_id}/store-performanceSnapshot actual units and cost to date for every activity and assignment of a saved version (the head by default, version_id, or an approved update's accepted version with update_period_id), with activity earned value and planned value to date, into a period that has ended at that version's data date. Optional note (up to 1,000 characters). Returns 201 with the run and the planned value basis (project_baseline or current_schedule). Periods are stored in date order and earlier ones are frozen. Storing the latest period again needs replace: true and appends a superseding run. 409 when the period hasn't ended, is frozen, is already stored without replace, or the update isn't accepted; 413 when there are too many rows.
GET /period-performanceThe effective run of every stored period in date order: actual units and cost to date and this period, earned value and planned value. With financial_period_id or run_id (not both), that run's activity and assignment rows, optionally filtered by activity_id and subject (activity or assignment).
GET /earned-valueBAC, BCWS, BCWP, ACWP, CV, SV, CPI, SPI, ETC, EAC and VAC per activity of the saved head version, from resource assignment costs, with the project's options (earned value and ETC technique) and each activity's performance_percent_complete under its WBS's technique, with the project baseline as the planned value basis (the current schedule when none is assigned), plus the latest stored period's actual this period. These feed the Planner's Earned Value columns. 409 when the stored schedule or project baseline fails its integrity check.

Runs and their rows are immutable and every store is audited. See Period performance and earned value.

Company portfolio and programs

Company endpoints live under /rest/v1.0/companies/{company_id}/schedules. Reads need schedule:read; writes need schedule:write. Schedule figures and links are returned only for projects where the caller is Schedule admin.

OperationBehaviour
GET /schedulesEvery project schedule the caller can see, with status (on_track, behind, negative_float, not_calculated, no_schedule, restricted), finish, float and health from stored calculations. Filter by region, stage, project_type, q, pm, status and program_id. Nothing is recalculated.
GET /schedules/program-links, POST /schedules/program-linksList or create inter-project links between two activities in different projects, with type (FS, SS, FF, SF), lag_days (−3,650 to 3,650), category and note. The caller must be Schedule admin on both projects.
PATCH /schedules/program-links/{link_id}, DELETE …Change a link's type, lag, category or note, or remove it. Endpoints can't change. No project schedule is affected.
GET /schedules/program-runs, POST /schedules/program-runs, GET /schedules/program-runs/{run_id}Calculate the linked projects' current versions as one read-only joint network (up to 25 projects and 2,000 links), choosing project_ids or a program_id, with optional slip_days (1–365) or an explicit slip. Each project's finish alone and in the program, cross-project driving paths and per-link delay come back. Calendars, total float method and open-end criticality apply per project. When network-wide options differ in a way that changes dates, the run is kept with status: option_conflict listing them; recalculate with align_to_project_id to take them from one project, and the result's option_resolution lists each override. Nothing is written to any project.
POST /schedules/program-runs/{run_id}/propose-constraintTurn one link's result into an open what-if scenario in the successor project, with a link_id and request_id. Nothing is adopted. Refused for runs with a loop or when the successor's schedule changed since the run.
GET /schedules/analysis-jobs, GET /schedules/analysis-jobs/{job_id}, POST /schedules/analysis-jobs/{job_id}/cancelCompany-scoped background jobs for program calculations. POST /schedules/program-runs queues large programs automatically, or on ?async=1 or Prefer: respond-async (202 with a Location), and runs inline with ?async=0. List by active, before_id and page_size. Reading or cancelling a job needs live Schedule admin on every project it covers.
GET /schedules/resourcesResource demand against capacity across up to 25 projects, from stored histograms, identity mappings and workforce reviews. Nothing is reserved or leveled.
POST /schedules/resource-levelingAdvisory cross-project leveling of the resources that retained identity mappings name in two or more projects the caller administers: project_ids (at least 2) or a program_id, horizon within_float (default) or extend_finish, and optional align_to_project_id. Returns a retained program run carrying resource_levelling (pools, moves and per-project proposals), inline or as a background job (?async=1 or Prefer: respond-async). A shared resource's capacity is the lowest any project states. Nothing is written to any schedule.
POST /schedules/program-runs/{run_id}/propose-levelingTurn one project's leveling moves into an open what-if scenario of start_on_or_after edits on its pinned version, with project_id and request_id. 201, or 200 on a replay. 409 when that project's schedule changed since the run. Nothing is adopted.

See Portfolio and programs. Opening several projects at once (read-only, in one grid and Gantt) is an app page with no REST endpoint yet: read each project's head and calculation, and the program links, with the endpoints above.

Map schedule resources to suite identities

Use GET /resource-inventory?source_type=material to find candidates. Supported source types are person, crew, equipment and material. Inventory accepts search, page and page_size (1–50). Live pagination does not represent one shared snapshot.

Send version_id and up to 500 explicit mappings to POST /resource-mappings/preview. Each mapping contains resource_id, source_type and source_id. Review units, source state, shared identities and unmapped resources. To retain that review, send the same selection plus expected_source_digest and expected_mapping_digest to POST /resource-mapping-reports. Changed source facts return 409 and require a fresh preview.

GET /resource-mapping-reports lists metadata with optional version_id, before_id and page_size (1–100); GET /resource-mapping-reports/{id} returns retained evidence without refreshing source facts. Inventory, preview and reads require schedule:read; retention requires schedule:write. Scoped tokens also need the selected owners’ workforce:read, equipment:read or materials:read. Live Schedule admin and owner view permissions are checked, including on historical reads. A history page with an inaccessible report is denied.

Retained mappings remain unapproved. Matching unit labels, crew membership, dispatch state and stock do not establish conversion, time-phased capacity or reservations. No dates, owner records, stock, rates, payroll or ledger actuals are changed.

Resource capacity and leveling proposals

Use POST /workforce-capacity/preview to compare a saved schedule with recorded person availability. Supply version_id, inclusive from_day/through_day (at most 366 days), and up to 100 mappings containing resource_id, person_id and an explicit positive minutes_per_unit conversion (at most 1440). This requires schedule:read, workforce:read, Schedule admin, Workforce view and company admin permission.

The preview uses unrounded daily engine demand, combines resources mapped to the same person and counts that person's supply once. Unknown availability, missing usage and inactive people remain qualified. Pending/confirmed direct and current-crew allocation overlaps require review: they are not assumed to be daily reservations and are not subtracted from supply. Source changes during calculation return 409. Conversions are user-stated, capacity remains uncertified, and the preview does not persist a report, reserve labor or change leveling or dates.

Save workforce evidence with POST /workforce-capacity/reports, the same selection and the preview's expected_review_digest. The digest covers results, source facts, mappings and engine/analysis revisions; observation timestamps are excluded. Saving repeats the preview and returns 409 if evidence changed. A new record returns 201; identical evidence saved by the same actor returns 200 with replayed: true. Saving requires schedule:write and the same owner permissions. This retains a snapshot, not an atomic approval of free capacity.

GET /workforce-capacity/reports lists metadata, with optional version_id, before_id and page_size (1–100). GET /workforce-capacity/reports/{id} returns original evidence without refreshing availability. Reads require schedule:read, workforce:read and current company/tool permissions. Saved evidence remains retained_unapproved.

Create a retained report with POST /resource-reports, an explicit version_id, and optional data_date. Omit analysis for a weekly histogram, or send analysis: { kind: "histogram", bucket: "day" }. Conflicts are evaluated daily even when the displayed buckets are weekly or monthly. Missing usage and capacity remain qualified in the result.

For leveling, send analysis: { kind: "leveling", horizon: "extend_finish", mode: "applied" }. The default horizon is within_float and the default mode is advisory. Here, applied includes proposed spans in the retained report; it does not apply dates to the saved plan or field tasks. Review unresolved conflicts, raised peaks, capacity coverage and calendar assumptions. The engine uses a deterministic heuristic, not a guarantee of an optimal schedule.

GET /resource-reports returns metadata history with optional version_id, before_id and page_size (1–100). GET /resource-reports/{id} reopens the original evidence. Creation requires schedule:write; reads require schedule:read. All three operations require live Schedule admin permission. Resource identities and capacity come from the schedule definition; they are not yet verified suite workforce, equipment or material availability. Planner provides native demand, conflict and leveling review with retained history and downloads. Explicit suite identity mappings are available through the workflow below; capacity validation and reviewed application of proposed dates remain in development.

Explain an activity date and retain the evidence

Send version_id, activity_id and optional data_date to POST /date-traces. This recalculates the explicit saved version using the CPM engine and returns 201 with an immutable explanation. An omitted data date uses the saved definition. Historical versions are supported; this operation does not require the current head and does not apply schedule or field dates.

The report includes the path to the activity, onward steps, driving ties and other compared relationships. The selected longest-path chain, tied driving set and zero total float are separate facts. Inspect actual-date handling, calendar/lag basis, precision, issues, violations and excluded relationships in the calculation qualifications. The wrapper retains the definition digest, input digest, engine revision, actor and creation time. This is a calculated explanation, not approval of imported dates or a delay claim.

GET /date-traces returns metadata with optional version_id, before_id and page_size (1–100). GET /date-traces/{id} reopens the original evidence without recalculation. Creation requires schedule:write; history and detail require schedule:read. All operations recheck live Schedule admin permission and project/company scope. Responses are private and not cached.

Malformed requests or untraceable networks return 400; field validation returns 422. Missing versions or activities return 404, and invalid retained evidence returns 409. Worker cancellation, capacity or availability can return 408, 429 or 503. Repeating a successful creation produces another record: after an uncertain response, inspect history before retrying. Creation and detail reject query parameters; history rejects unknown or repeated parameters.

Use the contract for the operation you need

All paths below follow /rest/v1.0/projects/{project_id}/schedule. See the generated Schedule reference for complete request schemas, response fields and errors.

OperationBoundary
GET /definitionRead the saved canonical plan and head.
POST /definitionSave against the expected head; this does not apply task dates.
POST /calculationsCalculate a saved version. Keep its version and calculation IDs.
GET /calculations/{id}/logRead a schedule calculation's log as JSON, text or CSV. See schedule log.
POST /date-traces, GET /date-traces, GET /date-traces/{id}Calculate and retain an activity date explanation, page through metadata history, or reopen original evidence.
POST /versions/diffCompare authored inputs in two saved versions, including exact activity fields, relationship multiplicity and project sections. Read-only; requires Schedule admin permission and a read token scope.
GET /baselines, POST /baselinesPage through named baselines or freeze an explicit saved version with a name and retry-safe request ID. Creating a baseline does not approve or publish it.
GET /baselines/{baseline_id}/timelineRead original saved activity dates with calculation, engine and definition provenance. Requires Schedule admin and schedule:read. No query parameters; unknown dates remain null. Missing original evidence returns 409. This does not recalculate or approve the baseline.
GET /imports/{import_id}/conversionReview retained-source identity, linked references and blockers.
POST /imports/{import_id}/conversion/adoptInitialize the first Planner version from a reviewed source; preserve task identity without applying dates.
GET /projectionReview calculated changes to eligible linked tasks without writing them.
POST /projection/applyRecheck the exact review and apply existing task dates explicitly.
GET /materialization/inventoryRead authorized native publication candidates and row digests; this is not a verified preview.
POST /materialization/previewVerify explicit decisions and review proposed task fields without writing them.
POST /materialization/applyRecheck and atomically apply the reviewed native publication decisions.
GET /hierarchy/inventoryPage through WBS/activity identities, existing row digests and eligible assignees.
POST /hierarchy/previewReview native hierarchy creation, parent moves and lifecycle decisions.
POST /hierarchy/applyAtomically publish the reviewed hierarchy and its calculated coverage.
GET /progress/inventory, POST /progress/preview, POST /progress/applyReview explicit percentage measures, rounding and actual-date changes; release-candidate acceptance is described below.
GET /imports, POST /imports, GET /imports/{import_id}List retained sources, upload a source for preview, and read a saved preview.
POST /imports/{import_id}/commitCommit an imported field schedule separately from adopting a canonical Planner version.
GET /imports/{import_id}/source, GET /exports/{import_id}Download the exact retained source. These downloads do not export subsequent Planner edits.
GET /versions/{version_id}/exportExport a saved version, with your edits, as XER, P6 XML or MSPDI. See export.
/analysis-jobs, /layouts, /updates, /submittals, /reports, /gantt-print, /assistant, /links, /cost-mappings, /cost-dashboardSee jobs, layouts, updates and submittals, reports, print and assistant, links and costs above. Company portfolio and program endpoints are under portfolio.

Authorize the complete review

Canonical plan operations require Schedule admin permission and an enabled Schedule tool. Source adoption, task-date projection and native publication also require Submittals and CRM admin permissions, with all three tools enabled. Full-network results may include private activities; ordinary field-view access is not sufficient.

Scoped tokens need schedule:read for reads and schedule:write for writes, plus submittals:read and crm:read for adoption, projection and native publication. The materialization preview is explicitly read-only despite using POST: inventory and preview require schedule:read; apply requires schedule:write. See authentication; scopes do not replace live project permissions.

Apply dates to an adopted import

Before saving or calculating, check the plan's WBS hierarchy. Each WBS ID must be unique, every parent and activity wbs_id must exist in that definition, and no parent chain may loop back to itself. Activity and WBS IDs are separate namespaces, so one activity and one WBS node may share the same ID. Invalid hierarchy returns 400 before a version or calculation is stored; the same checks apply to comparison and earned-value baselines. A raw import can remain available for inspection even when its hierarchy cannot be calculated or adopted. Saving valid WBS data does not publish it. Native plans use the separate hierarchy review below; imported hierarchy transitions still require reconciliation.

Request a preview with the required expected_version_id and optional calculation_id. Review blockers and every proposed change. The response includes a digest, version and calculation IDs, mapped and changed task counts, and date-only before/after values.

GET /rest/v1.0/projects/{project_id}/schedule/projection?expected_version_id=123

POST /rest/v1.0/projects/{project_id}/schedule/projection/apply
Content-Type: application/json

{
  "expected_version_id": 123,
  "calculation_id": 456,
  "preview_digest": "<digest returned by the reviewed preview>"
}

The IDs above are illustrative. Send the actual reviewed values. A change row has kind of activity or summary; derived summaries have a null activity_id. Unchanged mapped tasks are counted but omitted from the changes list.

Apply returns a receipt on success. An exact replay is accepted only while its applied snapshot remains current. On a conflict, obtain a new preview and review it; do not blindly retry a stale digest. Source changes, manual edits, mappings and calculation integrity can prevent application.

Review native publication decisions

This section describes the API contract. For the equivalent operator workflow, follow Publish a native field schedule from Planner. Planner versions with batched history scan beyond 64 saved versions, verifying every definition in batches of at most 64 versions and 16 MiB. The complete history response is limited to 50,000 identities and 2 MiB, with a 45-second scan budget. No partial history is returned. Earlier versions retain the 64-version ceiling. These editor limits are separate from publication receipt-history limits and this API contract.

Start with GET /materialization/inventory?expected_version_id=123, optionally selecting a calculation_id. The inventory returns authorized activity/task candidates, conditional actions, assignees and exact row digests. Its requires_preview is true and can_apply is false: submit the chosen decisions to the preview endpoint for engine verification. Never send the inventory's inventory_digest as an apply digest.

Submit an explicit decision list to preview. Use create for a new activity with an explicit privacy, assignee, baseline and unstarted-progress policy; bind for an eligible existing task; restore for its exact reserved retired identity; and retain or retire for remaining tasks. Existing-task decisions require task_id and the inventory's expected_row_digest. project appears in results for automatically projected existing bindings; it is not a submitted decision.

POST /rest/v1.0/projects/{project_id}/schedule/materialization/preview
Content-Type: application/json

{
  "expected_version_id": 123,
  "calculation_id": 456,
  "decisions": [{
    "operation": "create",
    "activity_id": "excavation",
    "private": true,
    "assigned_id": null,
    "baseline_policy": "none",
    "progress_policy": "unstarted"
  }]
}

This illustrative request assumes one eligible unbound activity and no other required decisions. Use actual IDs and the complete decision set from your review. Inspect global and row blockers, before/after fields, lifecycle changes and calculated coverage. Apply only when apply_supported and can_apply are true and the changes have been reviewed.

Send the same decisions to POST /materialization/apply, with the reviewed expected_version_id, required calculation_id and actual 64-character preview_digest. The response contains publication_id, version/calculation IDs, created_at, replayed and operation counts. Counts include unchanged retain/project operations. An exact replay is accepted only while the applied state is still current.

Native publication supports flat tasks and start/finish milestones with unstarted progress. Hierarchy and derived summaries, progressed work, imported/mixed history, unresolved manual changes and unsupported mappings or linked records can block it. Dependencies, resource assignments, working calendars and the data date are not copied into the field schedule. Retained tasks outside calculated coverage remain unknown for criticality.

Requests use strict snake_case, at most 10,000 decisions and 2 MiB JSON. Oversized inventories fail instead of silently truncating. Responses use private, no-store. On conflict, review again; do not change IDs or discard records merely to clear a blocker. Follow the native publication API walkthrough for a step-by-step review.

Review a native WBS hierarchy

On app versions exposing the hierarchy endpoints, use this workflow for native WBS summaries and unstarted activities. A WBS node and an activity may have the same opaque ID: every hierarchy decision uses an explicit identity with namespace set to wbs or activity. The activity-only materialization endpoints retain their flat-plan restrictions.

Read GET /hierarchy/inventory with required expected_version_id and calculation_id. Independently page nodes, tasks and assignees with node_page, task_page and assignee_page, each starting at 1. page_size defaults to 50 and cannot exceed 100. Compare inventory_digest across pages and discard mixed snapshots. Assignees are active project members; eligibility is checked again during publication.

Submit the reviewed decisions to POST /hierarchy/preview. Create requires explicit privacy, assignment, baseline and unstarted-progress policies. Create, bind, move and restore also require explicit nullable parent_wbs_id. Bind, move, restore, retain and retire require the existing task_id and exact expected_row_digest. Already-bound unchanged nodes project automatically. Requests use strict snake_case JSON, at most 20,000 decisions and 2 MiB.

POST /rest/v1.0/projects/{project_id}/schedule/hierarchy/preview
Content-Type: application/json

{
  "expected_version_id": 123,
  "calculation_id": 456,
  "decisions": [
    {
      "operation": "create",
      "identity": { "namespace": "wbs", "id": "phase" },
      "parent_wbs_id": null,
      "private": true,
      "assigned_id": null,
      "baseline_policy": "none",
      "progress_policy": "unstarted"
    },
    {
      "operation": "create",
      "identity": { "namespace": "activity", "id": "excavation" },
      "parent_wbs_id": "phase",
      "private": false,
      "assigned_id": null,
      "baseline_policy": "initial_dates",
      "progress_policy": "unstarted"
    }
  ]
}

This example assumes the saved plan contains exactly those unbound identities and no other required decisions. Preview shows existing task IDs only; new rows have a null task ID and reference new parents by WBS identity. Review every before/after row, then submit the same decisions to POST /hierarchy/apply with the returned preview_digest. A conflict requires fresh inventory and review. Exact replay is accepted only while the applied state remains current.

The same three-tool admin permissions and read/write token scopes apply. WBS summaries are private, unassigned and hidden from ordinary field readers, even if a later field edit changes their visibility flags. Assigned readers can see eligible private activities without gaining access to summary aggregates. Empty summaries, progressed work, imported/mixed transitions and unresolved field drift require further reconciliation. These routes do not publish canonical dependencies, resource assignments, calendars or the data date into field records.

Keep downstream semantics explicit

Adopted-import projection changes start, finish and critical flags on existing task IDs while preserving progress, baseline and actual dates, privacy and assignments. Native publication follows the explicit lifecycle and creation policies in its review. Linked submittal task displays read the task dates, but independent due and procurement dates do not move. CRM reviewed snapshots can become stale; neither workflow rewrites or publishes customer updates.

A task response's raw critical flag is stored data. Dependency responses expose criticality_source and nullable on_critical_path; null means unavailable, not false. Never treat retained flags as proof of a current calculation.

  • true: the task is covered by the selected calculation and is critical.
  • false: the task is covered by the selected calculation and is noncritical.
  • null: criticality cannot be verified for this task, including when it falls outside an applied result's calculated coverage.

Keep the value and its criticality_source together. planner_projection identifies verified applied Planner results; legacy_calendar_days uses visible dependencies and calendar-day durations, not working calendars. unavailable must remain unknown in your UI. Do not replace null with a stored task flag or a false value. A newer saved Planner version does not change field criticality until it is applied.

Plan save accepts a nullable expected head; initial adoption requires a null expected head. Projection requires positive version and calculation IDs. These are different contracts, not interchangeable forms of the same write.

Reviewed progress publication — release candidate

The progress API is implemented in the release candidate; browser and deployment acceptance are still in progress. Verify endpoint availability in your deployed version. Under /rest/v1.0/projects/{project_id}/schedule, use GET /progress/inventory, POST /progress/preview and POST /progress/apply. All three require Schedule, Submittals and CRM administrative permissions with those tools enabled. Inventory and preview require schedule:read; apply requires schedule:write. All require submittals:read and crm:read.

Inventory requires expected_version_id and calculation_id. It returns raw and normalized duration/physical measures, local actual timestamps, current field values and exact row digests. Pages share an inventory_digest; never combine pages with different digests. Inventory selects no measure or rounding rule and does not authorize apply.

Preview uses the hierarchy decision shapes plus required progress_decisions. Each progress decision identifies an activity and supplies task_id, expected_row_digest, policy and allow_actual_date_clearing. For a new task both row fields are null, and its create decision uses progress_policy: "reviewed". For an existing task both fields must match the reviewed row. A policy contains percentage_basis (duration or physical), rounding (nearest, floor or ceil), and actual_date_policy: "local_calendar_date". Missing progress is never inferred as zero.

Apply sends the same decisions with the returned preview_digest. It atomically writes the reviewed task values, ownership, receipt and active publication. Replays require the same actor, request and resulting state. Responses are private and no-store. Limits are 20,000 hierarchy decisions, 10,000 progress decisions and 2 MiB per request. WBS progress is not inferred; field observations, imported/mixed transitions and canonical dependencies/resources/calendars/data date are not published by this workflow.

Continue with the API reference, operator guide or schedule-review tutorial.

Retained conformance assessments — release candidate

GET /schedule/conformance lists assessment metadata without loading full reports. Use page_size (1–100, default 25), optional version_id, and pass next_before_id back as before_id for older results. This requires read scope and Schedule admin permission. The native Planner supports assessment creation, retained history, finding filters and paginated report review; richer governing-term controls and report exports remain in development.

Use POST /schedule/conformance under the project REST prefix with an explicit version_id. Optional conformance parameters are spec, jurisdiction, contract_names, elected, terms and is_baseline; an optional data_date overrides the calculation date. Omitted governance uses the original service's neutral profile. Historical versions are supported. Creation requires schedule:write; GET /schedule/conformance/{id} requires schedule:read. Both require live Schedule admin permission.

The response retains the version and definition digest, input digest, engine revision, parameters and original report. Read coverage and inputs_required alongside the verdict: a pass does not mean every rule could be assessed. Baseline designation and contract terms are caller declarations, not approval records. Creating an assessment changes neither the current plan nor published tasks; repeated requests create separate assessments. Broader forensic investigation workflows remain in development. Verify deployed endpoint availability before relying on this release candidate.

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