GuidesAPI DocsChangelogMy AppsSeismic Exchange
API Docs

Update an existing program

put
https://api.seismic.com/programs/v2/spaces//programs/

Updates an existing program with new values for title, description, manager, dates, custom properties,
associations, phases, analytics settings, and Slack integrations. All fields in the request body will replace existing values.
This is a full update operation - use PATCH for partial updates.

Key Features:

  • Updates all program metadata including title, description, and dates
  • Changes program manager assignments
  • Modifies custom properties and their values
  • Updates content and task associations
  • Adjusts workflow phases and current phase
  • Modifies analytics settings including launch dates and metrics
  • Updates Slack channel connections
  • Maintains version history and audit trails for compliance

Authorization Logic:

  1. User must have a valid JWT token with management scopes
  2. User must have program update permissions
  3. User must have permission to update the specific program
  4. If managerId is provided, the manager must be a valid user in the tenant

Usage Example:

Update a program's planned dates, change the assigned manager, modify custom properties, add new content
associations, or update analytics tracking for a campaign.

Path Params
string
required
length between 7 and 22

The unique identifier of the space containing the target entity. This determines the scope of entity queries and ensures proper access control. The space must be accessible to the authenticated user with appropriate permissions. It can be the unique identifier (GUID) of the space or the word "default" to indicate the default programs space. Common values include "default" and "rkr83lapKkyCJuLLWqLqzB".

string
required

The unique identifier of the program to update. Must be a valid program ID within the specified space.

Body Params

The complete program data to update. All fields provided will replace existing values.

string

Human-readable display name for the program used throughout the application in program lists, dashboards, reports, and navigation interfaces. Typically 3-100 characters clearly identifying the program's purpose and scope. Required field when updating to maintain clear program identification. Should be concise yet descriptive enough to differentiate this program from others in the workspace. Examples include 'Q1 2025 Product Launch', 'Annual Sales Kickoff - Updated', or 'Marketing Campaign Refresh'. Use professional, business-appropriate naming that helps stakeholders quickly identify the program without requiring additional context. Appears in program selectors, assignment notifications, and analytics dashboards. Cannot be empty or whitespace-only.

string

Detailed explanatory text describing the program's objectives, scope, key deliverables, target outcomes, and any relevant background context that helps stakeholders understand the program's purpose and expected results. Supports multi-line plain text, typically 50-1000 characters. Optional field (nullable) that provides comprehensive context beyond the title. Use this to document business justification, strategic alignment, target audience, success criteria, dependencies, and key milestones. Examples include outlining specific goals like 'Launch new product line targeting enterprise customers with $5M revenue target' or 'Onboard 50 new sales representatives across 3 regions with 90-day ramp-to-productivity plan'. This description appears in program detail views, project charters, and status reports helping team members and executives understand program intent and expectations.

date-time | null

Target date and time when the updated program is scheduled to begin execution, represented in ISO 8601 format (e.g., '2025-01-20T00:00:00Z'). Optional field (nullable) used for timeline planning, resource scheduling, and milestone tracking. When updating a program, modify this date to reflect schedule changes, delays, or accelerated timelines. Supports full date-time precision including timezone for accurate cross-regional coordination. Use when program start dates shift due to dependency changes, resource availability, stakeholder decisions, or external factors. Setting to null removes the planned start date entirely. This date appears in program calendars, Gantt charts, timeline views, and scheduling reports. Combined with plannedEndDate enables automatic duration calculations and deadline tracking.

date-time | null

Target completion date and time when the updated program is scheduled to finish, represented in ISO 8601 format (e.g., '2025-04-15T00:00:00Z'). Optional field (nullable) critical for deadline tracking, milestone management, and completion planning. When updating a program, adjust this date to reflect revised timelines, extended deadlines, or accelerated delivery schedules. Should be chronologically after plannedStartDate when both are specified. Supports full date-time precision including timezone. Use when program deadlines change due to scope adjustments, resource constraints, stakeholder requests, or external factors impacting delivery. Setting to null removes the planned end date constraint entirely. This date appears in deadline reports, program dashboards, completion forecasts, and risk assessments. Enables duration-based analytics and late-detection warnings for proactive program management.

int32

Expected length of the updated program measured in calendar days from start to finish, represented as a positive integer value. Optional field that can be explicitly set or automatically calculated from plannedStartDate and plannedEndDate. Typical range is 1-365 days for most programs, though longer durations are supported for multi-year strategic initiatives. When updating a program, modify this to reflect revised timelines, scope changes, or resource availability adjustments. Use when planning program phases, estimating resource commitments, calculating project velocity, and forecasting completion dates. For example, extending from 85 to 120 days to accommodate additional testing phases or market delays. This duration appears in capacity planning tools, resource allocation dashboards, and program comparison analytics. Must be positive integer when specified. Useful for duration-based reporting and timeline-impact analysis during program replanning efforts.

customProperties
array of objects | null

Array of custom property values to update or set on the program, enabling organizations to modify business-specific metadata such as budget codes, strategic themes, regional classifications, campaign identifiers, cost center assignments, or departmental tags. Each CustomPropertyValues entry references a custom property definition configured in the space and provides the updated value(s) to apply. Optional field (nullable) that allows partial updates - omit to leave existing custom properties unchanged, or provide new values to update specific properties while preserving others. Use when organizational metadata changes due to budget reallocations, team restructuring, campaign reassignments, or taxonomy updates. For example, update budget code when programs transfer between cost centers, or change regional classification when program scope expands to new markets. Empty array clears all custom properties. Enables flexible categorization and filtering based on evolving organizational needs without schema modifications. Updated values immediately affect program filtering, reporting, and analytics groupings.

customProperties
string | null

Unique identifier of the user to assign or reassign as the program manager or owner, represented in GUID format (e.g., 'u67890-new-manager-xyz'). Optional field (nullable) used for ownership transfers, responsibility reassignments, or manager succession during organizational changes. When updating a program, set this to a new user ID to transfer program management responsibilities including oversight, approval authority, and accountability. The specified user must have appropriate permissions and access to the space. Set to null to remove the manager assignment entirely, creating an unmanaged program. Use when managers change due to personnel transitions, workload rebalancing, organizational restructuring, or delegation needs. Updated manager receives notifications, gains elevated permissions for program modifications, and becomes the primary contact for program-related decisions. This change is tracked in audit logs and reflected in assignment reports, ownership dashboards, and responsibility matrices.

analyticSetting

Comprehensive analytics configuration object to update for the program including launch dates, lifecycle phases, target audiences, KPI metrics, objectives, topics, external tracking integrations, and program type classification. Optional field (nullable) that enables updating advanced analytics capabilities such as phase-based progress tracking, audience segmentation, metric definitions, and outcome-oriented success criteria. When specified, replaces the existing analytics configuration with new settings. References ProgramAnalyticSettingInput schema containing detailed analytics structures. Set to null to remove analytics tracking entirely. Use when program goals evolve requiring new KPIs, when audience segments change due to market shifts, when phase timelines adjust requiring milestone updates, or when integrating new tracking systems. For example, update analytics when shifting from revenue-focused metrics to engagement-focused metrics, or when adding new program phases for extended delivery cycles. Updated analytics settings immediately affect dashboards, reporting queries, metric calculations, and phase-based progress indicators enabling data-driven program management aligned with current strategic priorities.

Responses

Updated about 4 hours ago

Language
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated about 4 hours ago