Skip to content

API Reference

Complete reference for all resolver functions registered in foundation/src/index.ts. Resolvers are invoked from the frontend via @forge/bridge invoke(name, payload).

All resolvers receive { payload, context } where context.accountId is the authenticated Jira user and context.cloudId is the Jira Cloud site ID.



List all lenses the current user can access.

GuardswithSchema
PermissionReturns lenses where user is owner or has any grant
Payload(none)
Returns{ lenses: Array<{ id, numeric_id, name, description, mode, owner_account_id, archived, issue_count, sync_agent_count, created_at, updated_at }> }

Create a new lens with a default view.

LicenseRequired
Payload{ name: string, description?: string }
Returns{ lens: { id, name, ... } }
ErrorsName is required, license_inactive
Side effectsCreates a default view; rolls back lens on view creation failure

Rename or update a lens description.

LicenseRequired
Permissioncontrol on the lens
Payload{ lensId: string, name: string, description?: string }
Returns{ success: true }

Delete a lens and all associated data.

LicenseRequired
Permissioncontrol on the lens
Payload{ lensId: string }
Returns{ success: true }

Primary data-loading endpoint. Returns the full hierarchy tree, views, sync agents, and permissions for a lens.

LicenseRequired
Permissionview (returns user’s permission level for UI gating)
Payload{ lensId?: string, numericId?: number }
Returns{ rows, columns, views, syncAgents, lens, totalCount, userPermissionLevel, edition, ... }
NotesSupports friendly URL lookup via numericId. Filters issues by Jira BROWSE permission. Triggers auto-sync staleness check.

Add an existing Jira issue to a lens by its issue ID or key.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, issueIdOrKey: string, parentId?: string }
Returns{ node: HierarchyNode, issueData: CachedIssue }
ErrorsIssue already exists in this lens

Create a new Jira issue and add it to the lens in one operation.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, summary: string, projectKey: string, issueTypeName?: string, parentId?: string, parentIssueKey?: string, parentIssueId?: string }
Returns{ node, issueData }
API Cost4+ points (create issue + fetch + cache)

Get the project key context for a lens (inferred from sync agents).

Permissionview on the lens
Payload{ lensId: string }
Returns`{ projectKey: string

Get project key + issue types for inline issue creation.

Permissionview on the lens
Payload{ lensId: string, parentIssueKey?: string }
Returns{ projectKey, issueTypes, parentIssueId }

Add a non-Jira grouping node (flex item) to the hierarchy.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, name: string, parentId?: string, description?: string, icon?: string }
Returns{ node: HierarchyNode }

Add a milestone marker to the hierarchy.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, name: string, date: string, parentId?: string }
Returns{ node: HierarchyNode }

Move a node to a new parent and/or position in the hierarchy.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, nodeId: string, newParentId?: string, newPosition?: number, beforeNodeId?: string, afterNodeId?: string }
Returns{ success: true }

Remove a node (and optionally its subtree) from the hierarchy.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, nodeId: string, deleteChildren?: boolean }
Returns{ success: true, deletedCount }

Add multiple Jira issues to a lens by their issue keys.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, issueKeys: string[], parentId?: string }
Returns{ added, skipped, errors }

Update a Jira issue field and sync the cache.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, issueKey: string, field: string, value: any }
Returns{ success: true, updatedFields?: { status_name, status_category, assignee_display_name, ... } }
API Cost4 points (2 for update + 2 for refetch); status transitions cost 4-6 points
SecurityVerifies issue belongs to the specified lens to prevent cross-lens modification
NotesHandles start_date field ID resolution dynamically (QA-BUG-72). Status field triggers a transition workflow instead of a direct PUT.

Supported fields and their Jira mappings:

Client FieldJira API Field
summarysummary
statusTransitions API (special)
assigneeassignee (wrapped as { accountId })
reporterreporter (wrapped as { accountId })
prioritypriority (wrapped as { id })
duedate / due_dateduedate
start_dateResolved dynamically (customfield_10015 or customfield_10068)
labelslabels
story_pointscustomfield_10016
sprintcustomfield_10020 (plain integer, not { id })
componentscomponents
fixVersionsfixVersions
affects_versionsversions
customfield_*Passed through directly

Get available status transitions for an issue.

Permissionview on the lens (optional lensId)
Payload{ issueKey: string, lensId?: string }
Returns{ transitions: Array<{ id, name, toStatusId, toStatusName, toStatusCategory }> }
API Cost2 points

Get all Jira priority levels.

AuthRequired
Payload(none)
Returns{ priorities: Array<{ id, name, iconUrl }> }
API Cost1 point

Get sprints for a board.

AuthRequired
Payload{ boardId: string }
Returns{ sprints: Array<{ id, name, state }> }

Get available options for a custom field on a specific issue.

AuthRequired
Payload{ issueKey: string, fieldId: string }
Returns{ options: Array<{ id, value, ... }> }
API Cost1 point

Get components for a project (KVS-cached, 1-hour TTL).

AuthRequired
Payload{ projectKey: string }
Returns{ components: Array<{ id, name }> }

Get versions for a project (KVS-cached, 1-hour TTL).

AuthRequired
Payload{ projectKey: string }
Returns{ versions: Array<{ id, name, released }> }

List all views for a lens.

GuardswithSchema, withLensPermission('view')
Payload{ lensId: string }
Returns{ views: Array<{ id, lens_id, name, is_default, columns, settings_json, ... }> }

Update a view’s configuration (columns, formatting, Gantt settings, etc.).

LicenseRequired
Permissionedit on the lens
Payload{ viewId: string, columns?, name?, density?, wrapRows?, formattingRules?, ganttEnabled?, ganttWidth?, ganttScale?, sortConfig?, pipeline?, ... }
Returns{ success: true }

Create a new view for a lens.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, name: string, columns?: array }
Returns{ view: { id, lens_id, name, columns, ... } }

Delete a view (cannot delete the default view).

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, viewId: string }
Returns{ success: true }
ErrorsCannot delete the default view

Set which view is the default for a lens.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, viewId: string }
Returns{ success: true }

Create a new sync agent for a lens.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, generatorType: string, config: object, parentNodeId?: string }
Returns{ generator: { id, lens_id, generator_type, config, ... } }

List all sync agents for a lens.

Permissionview on the lens
Payload{ lensId: string }
Returns{ syncAgents: Array<{ id, lens_id, generator_type, config, last_executed_at, ... }> }

Update a sync agent’s configuration.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, generatorId: string, config?: object, parentNodeId?: string }
Returns{ success: true }

Delete a sync agent.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, generatorId: string }
Returns{ success: true }

Reorder sync agents for a lens.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string, orderedIds: string[] }
Returns{ success: true }

Trigger async execution of all sync agents for a lens.

LicenseRequired
Permissionedit on the lens
Payload{ lensId: string }
Returns{ status: 'executing', jobId: string }
ErrorsSync agents are already running for this lens
NotesPushes to the generator-queue with per-lens concurrency. Uses KVS lease to prevent double-dispatch. Active job marker has 15-min TTL.

Check if any sync agents need re-execution based on JQL result count changes.

Payload{ lensId: string }
Returns{ stale: boolean, details: ... }

Get all permission grants for a lens.

GuardswithSchema, withLensPermission('control')
Payload{ lensId: string }
Returns{ permissions: Array<{ id, lens_id, grantee_type, grantee_id, permission_level }> }

Grant a permission on a lens.

Permissioncontrol on the lens
Payload`{ lensId: string, granteeType: ‘user'
Returns{ permission: { id, ... } }
ValidationRuntime enum checks on granteeType and permissionLevel. granteeId required for non-everyone grants.

Revoke a specific permission grant.

Permissioncontrol on the lens
Payload{ lensId: string, permissionId: string }
Returns{ success: true }

Search Jira users (for permission sharing dialogs).

GuardswithSchema, withAuth
Permissionview on the lens
Payload{ lensId: string, query: string }
Returns{ users: Array<{ accountId, displayName, avatarUrl }> }
APIUses asApp()/rest/api/3/user/search

Search users assignable to issues in a specific project.

Permissionedit on the lens
Payload{ lensId: string, query: string, projectKey?: string }
Returns{ users: Array<{ accountId, displayName, avatarUrl }> }
APIUses asUser()/rest/api/3/user/assignable/search scoped to project

Search Jira groups.

GuardswithSchema, withAuth
Permissionview on the lens
Payload{ lensId: string, query: string }
Returns{ groups: Array<{ name }> }

Transfer lens ownership to another user.

PermissionMust be the lens owner or a Jira site admin
Payload{ lensId: string, newOwnerAccountId: string }
Returns{ success: true, newOwnerAccountId }

Create a Jira issue link (dependency) between two issues.

Permissionedit on the lens
Payload`{ lensId: string, fromIssueKey: string, toIssueKey: string, dependencyType?: ‘FS'
Returns{ success: true, linkId }
ValidationCycle detection before creating the link

Delete a Jira issue link.

Permissionedit on the lens
Payload{ lensId: string, linkId: string }
Returns{ success: true }

Get available Jira issue link types.

AuthRequired
Returns{ linkTypes: Array<{ id, name, inward, outward }> }

Get dependency links for issues in a lens.

Permissionview on the lens
Payload{ lensId: string }
Returns{ links: Array<{ ... }> }

Update the lag days for a dependency.

Permissionedit on the lens
Payload{ lensId: string, fromIssueKey: string, toIssueKey: string, lagDays: number, dependencyType?: string }
Returns{ success: true }

Get all dependency lag overrides for a lens.

Permissionview on the lens
Payload{ lensId: string }
Returns{ lags: Array<{ fromIssueKey, toIssueKey, lagDays, dependencyType }> }

Fetch all Jira fields (standard + custom) with type classification.

AuthNone (app-level)
Payload(none)
Returns{ fields: Array<{ id, name, type, isCustom }> }
API Cost1 point
NotesMaps Jira custom field schemas to Foundation types (e.g., com.pyxis.greenhopper.jira:gh-sprint -> sprint)

Resolve the work issue type hierarchy for a project.

Payload{ projectIdOrKey?: string }
Returns{ hierarchy: Array<{ level, issueTypes }> }

Poll the status of an async job (sync agent execution, etc.).

AuthRequired
Payload{ jobId: string }
ReturnsJob status object from KVS, or { status: 'unknown' }
SecurityValidates jobId format (hex/dash, max 64 chars). Verifies caller has view permission on the job’s lens (AUDIT-009).

Get a signed Forge Realtime token for subscribing to lens events.

Permissionview on the lens
Payload{ lensId: string }
Returns{ channel: string, token: string }
Errors{ channel, token: '', error: 'realtime_unavailable' } if signing fails

Get the current rate limit budget status.

AuthRequired
Returns{ remaining, used, limit, resetsAt }

All admin resolvers require the user to be a Jira site admin.

Get app-wide statistics.

GuardswithSchema, withAdmin
Returns{ cachedIssues, lenses, hierarchyNodes, rateLimitUsagePercent }

Trigger a synchronous full cache refresh (legacy).

AdminRequired
Returns{ refreshed, removed }
NotesHas 10-minute cooldown. Replaced by startCacheRefresh for async operation.

Start an async per-project cache refresh.

AdminRequired
Payload{ projectKeys: string[] } (max 20)
Returns{ status: 'queued', jobId, projectCount, budget }
NotesPushes one queue message per project to cache-refresh-queue.

Poll the status of a cache refresh job.

AdminRequired
Payload{ jobId: string }
ReturnsCacheRefreshJob object with per-project status

Get per-project cache statistics.

AdminRequired
Returns{ projects: Array<{ projectKey, issueCount, oldestCached, newestCached }> }

Set/get custom CSS overrides for the app.

setCssOverrideAdmin required. { css: string } (max 50KB).
getCssOverrideNo auth required (all users load CSS). Returns { css }.

Check if the current user is a Jira site admin.

Returns{ isAdmin: boolean }

Wipe ALL Foundation data (reset to clean install).

AdminRequired
Returns{ success: true }
NotesDeletes children-first for crash safety. Sets KVS recovery flag before starting.

Get installation statistics for Tier 2 application.

AdminRequired
Returns{ totalCachedIssues, totalLenses, totalHierarchyNodes, uniqueProjects, avgHourlyPointUsage, peakHourlyPointUsage, currentTier, currentBudget }

Set the rate limit tier budget override.

AdminRequired
Payload{ budget: number } (65,000 - 500,000)
Returns{ success: true, budget }

Get announcement IDs the current user has dismissed.

Returns{ dismissed: string[] }

Mark an announcement as dismissed.

Payload{ id: string }
Returns{ success: true }

Check if the current user is a Jira admin (used by announcement audience filtering).

Returns{ isAdmin: boolean }

Run portfolio analysis on a lens to generate insights.

Permissionview on the lens
Payload{ lensId: string }
Returns{ insights: Array<{ id, insight_type, severity, summary, affected_nodes, suggested_action }> }
Side effectsClears stale insights, persists new ones to ai_insights table, publishes analysis_complete realtime event

Analyze a specific section of the hierarchy for missing items.

Permissionview on the lens
Payload{ lensId: string, anchorName?, anchorIssueKey?, anchorNodeId?, maxMissingItems? }
Returns{ gaps: Array<{ ... }> }

Get workload analysis for resources in a lens.

Payload{ lensId: string }
ReturnsWorkload data with resource allocations

Get workload aggregated across multiple lenses.

ReturnsCross-lens workload data

Find the best matching resource for a task based on skills and availability.

Payload{ lensId: string, ... }
ReturnsRanked list of matching resources

listTeams / createTeam / updateTeam / deleteTeam

Section titled “listTeams / createTeam / updateTeam / deleteTeam”

Full CRUD for teams.

Payload{ name, description?, color?, isGlobal?, lensId? } (create/update)

Manage team membership.

Payload{ teamId, resourceId, availabilityPct?, startDate, endDate? } (add)

listHolidayCalendars / createHolidayCalendar / deleteHolidayCalendar

Section titled “listHolidayCalendars / createHolidayCalendar / deleteHolidayCalendar”

Holiday calendar CRUD.

listHolidayDates / addHolidayDate / removeHolidayDate

Section titled “listHolidayDates / addHolidayDate / removeHolidayDate”

Manage individual holiday dates within a calendar.

Assign a holiday calendar to a resource.


listAbsences / createAbsence / deleteAbsence

Section titled “listAbsences / createAbsence / deleteAbsence”

Resource absence tracking.

Payload{ resourceId, startDate, endDate, isHalfDay?, absenceType?, notes? } (create)

createBaseline / listBaselines / getBaselineEntries / deleteBaseline

Section titled “createBaseline / listBaselines / getBaselineEntries / deleteBaseline”

Baseline snapshot management. A baseline captures a point-in-time snapshot of node dates for comparison.

Payload{ lensId, name } (create)
Returns{ entries: Array<{ nodeId, jiraIssueKey, startDate, endDate }> } (getEntries)

Start an async resource leveling job for a lens.

Payload{ lensId: string }
Returns{ jobId: string }

Poll leveling job status.

Payload{ jobId: string }
ReturnsLeveling job status object

Reset leveling results for a lens.

Payload{ lensId: string }

Skill taxonomy management.

Payload{ name, category?, color? } (create)

assignSkillToResource / removeSkillFromResource / getResourceSkills

Section titled “assignSkillToResource / removeSkillFromResource / getResourceSkills”

Manage resource skill assignments with proficiency levels.


createPlaceholder / listPlaceholders / resolvePlaceholder / deletePlaceholder

Section titled “createPlaceholder / listPlaceholders / resolvePlaceholder / deletePlaceholder”

Placeholder resource management. Placeholders represent unfilled roles that can later be resolved to real resources.


Delete or anonymize ALL personal data for a user.

AdminRequired
Payload{ targetAccountId: string }
Returns{ success: true, deletions: Record<string, number>, timestamp }
ScopePermissions, lens ownership, issue cache PII, hierarchy nodes, generators, leveling jobs, baselines, dependency overrides, resources, team memberships, absences, schedules, skills, calendar assignments, views, automation rules, alerts, KVS entries (prefs, announcements, chat, feedback cooldown)

Generate a comprehensive data report for a user (GDPR data access request).

AdminRequired
Payload{ targetAccountId: string }
ReturnsObject with all data categories (lenses, permissions, issues, nodes, etc.)

KVS-backed per-user preferences.

StorageKVS key user_prefs:${accountId}

In-app support chat for users.

getAdminSupportInbox / getAdminSupportThread / replySupportMessage

Section titled “getAdminSupportInbox / getAdminSupportThread / replySupportMessage”

Admin-side support chat management.

GuardswithSchema, withAdmin

Search for Jira issues (used by issue link picker).

Payload{ query: string, lensId?: string }
Returns{ issues: Array<{ id, key, summary, ... }> }

Search Jira projects or list projects available for import.

List Jira Product Discovery projects.

Get which lenses contain a specific issue (for issue context panel).

Payload{ issueKey: string }
Returns{ lenses: Array<{ id, name }> }

previewStructureImport / executeStructureImport / getStructureImportStatus

Section titled “previewStructureImport / executeStructureImport / getStructureImportStatus”

Third-party hierarchy import (disabled).

previewBigPictureImport / executeBigPictureImport / getBigPictureImportStatus

Section titled “previewBigPictureImport / executeBigPictureImport / getBigPictureImportStatus”

Third-party PPM import (disabled).

CSV/Excel import with chunked processing.

validateExportFile / executeExportFileImport / getExportFileImportStatus

Section titled “validateExportFile / executeExportFileImport / getExportFileImportStatus”

DC-to-Cloud export file import.

Project-based hierarchy import.


Feature flag management (KVS-backed).

setFeatureFlagAdmin required

Get the monitoring dashboard data.

GuardsAdmin required
ReturnsAggregated resolver metrics, error rates, performance data

Get detailed metrics for specific resolvers.

GuardsAdmin required

Delete old monitoring data.

GuardsAdmin required

Health check endpoint (schema verification).

MetricsSkipped
Returns{ status: 'ok', version: '0.1.0' }

Manual sync trigger (legacy).

Validate a JQL query against Jira.

Payload{ jql: string }
Returns{ valid: boolean, errors?: string[] }

Get an incremental diff of changes after sync agent execution.

Payload{ lensId: string, jobId: string }

Initialize lens context (prefetch data for the lens view).

Track the user’s most recently visited lens for auto-navigation.

Forward frontend errors to Sentry (bypasses CSP restrictions).

MetricsSkipped
Payload{ message, stack, component, extra? }

Log client-side icon fallback events.

MetricsSkipped

checkDeletePermissions / deleteIssuesFromJira

Section titled “checkDeletePermissions / deleteIssuesFromJira”

Check delete permissions and delete Jira issues.

Permissionedit on the lens

Submit in-app feedback.


The Forge manifest has a limited number of action slots. To fit more functionality, several actions use a dispatcher pattern where a single manifest action routes to multiple sub-actions via a _action parameter.

Hierarchy metadata dispatcher.

Sub-actionDescription
getTransitionsGet available status transitions
getFieldOptionsGet field options for a field
getLensDetailsGet lens detail data
getNodeDetailsGet details for a specific node
getSubtreeStatsGet statistics for a subtree
groupNodesByGroup nodes by a field
sortNodesSort nodes by a field
renameFlexItemRename a flex item
flattenSubtreeFlatten a subtree (move children to parent)
mergeFlexItemsMerge multiple flex items into one

View and permission dispatcher.

Sub-actionDescription
createViewCreate a view
deleteViewDelete a view
setDefaultViewSet the default view for a lens
grantPermissionGrant a permission
revokePermissionRevoke a permission

Lens CRUD dispatcher.

Sub-actionDescription
createLensCreate a new lens
renameLensRename a lens
deleteLensDelete a lens

Jira utility dispatcher.

Sub-actionDescription
validateJqlValidate a JQL query
analyzeJiraProjectAnalyze a Jira project
createFromTemplateCreate lens from template

Read-only intelligence/analytics dispatcher (auto-executes, no confirmation).

Sub-actionDescription
getHealthScorePortfolio health score
getRiskAssessmentRisk assessment analysis
getWorkloadAnalysisWorkload distribution analysis
getBottleneckAnalysisBottleneck detection
getStructureQualityHierarchy structure quality
getDriftAnalysisSchedule drift analysis
getSprintIntelligenceSprint intelligence metrics
getPortfolioIntelligencePortfolio-level intelligence
getTrendAnalysisTrend analysis over time
searchAcrossLensesSearch across all lenses
getPortfolioOverviewPortfolio overview dashboard
compareLensesCompare two or more lenses
getLensStatisticsDetailed lens statistics
generateStatusReportGenerate a status report
getPendingAlertsGet pending alerts
listAutomationRulesList automation rules
getAlertHistoryGet alert history
getContextualSuggestionsAI contextual suggestions
getWbsJobStatusWBS generation job status

Destructive operations dispatcher (requires user confirmation).

Sub-actionDescription
archiveLensArchive a lens
transferOwnershipTransfer lens ownership
duplicateLensDuplicate a lens
cloneLensFilteredClone with filters
splitLensByFieldSplit lens by field value
mergeLensesMerge multiple lenses
cleanupLensClean up stale data
rebalanceWorkloadRebalance workload across resources
restructureByFieldRestructure hierarchy by field
dismissAlertDismiss an alert
configureAlertThresholdsConfigure alert thresholds
configureAutoRuleConfigure an automation rule
deleteAutomationRuleDelete an automation rule
scheduleIssueTimelineSchedule issue timeline