> ## Documentation Index > Fetch the complete documentation index at: https://docs.agile-tools.io/llms.txt > Use this file to discover all available pages before exploring further. # Update KPI > Applies JSON Merge Patch semantics to mutable KPI fields. ## OpenAPI ````yaml /openapi.v1.local.json patch /v1/public/kpis/{id} openapi: 3.0.3 info: title: Agile Tools Public API description: >- REST API for integrating external systems with Agile Tools. ## Authentication Most endpoints require an `X-API-Key` header containing a valid owner-typed API key. Supported ownership types are `ORGANIZATION`, `PERSON`, and `VALUE_UNIT`. Anonymous library browsing endpoints use short-lived session tokens instead. ## Scope Behavior Wildcard scope (`*`) is organization-only. Value-unit keys are restricted to value-unit-centric endpoint families and descendant scope checks. Personal keys default to personal-empty scope unless explicit permissions are granted. Cross-organization key governance is out of scope for `/v1/public/*` and is handled by `/v1/sys/public-api-keys`. ## Rate Limiting Requests are rate-limited per API key based on your subscription plan. When a limit is exceeded the API returns `429 Too Many Requests` with a `Retry-After` header. ## Idempotency POST and PUT requests support idempotent replay via the optional `Idempotency-Key` header. Selected high-risk KPI and Health Metric write endpoints require this header to ensure safe retries without duplicate side-effects. ## Response Envelope Public v1 and v2 response contracts coexist during migration. Authenticated public endpoints use `PublicApiKeyMeta` semantics (`requestId`, `timestamp`) and anonymous public endpoints use `PublicAnonymousMeta` semantics. Anonymous library endpoints may add `PublicAnonymousLibraryMeta` tab-count metadata while authenticated public endpoints do not define a library tab-count metadata branch. ## Public Docs Visibility Policy Published public docs intentionally exclude anonymous Sessions and Library endpoints. Those v1 anonymous flows remain runtime-stable but are not listed in Mintlify-facing OpenAPI output. ## Migration Guidance For list endpoints, migrate in stages: keep v1 stable, adopt v2 offset mode first, then adopt v2 cursor mode where needed. Fallback expectation: clients may continue using v1 while v2 adoption is rolled out incrementally. ## Versioning & Deprecation Policy Breaking changes require a new major version (`/v2/`). Non-breaking additions ship in the current version. Deprecated endpoints include a `Sunset` HTTP header with the removal date. Minimum notice period: 6 months. contact: name: Agile Tools Developer Support url: https://teampoolz.mintlify.app email: dev-support@agile-tools.io version: 1.0.0 servers: - url: https://api.agile-tools.io description: Production - url: https://api.alpha.agile-tools.io description: Staging - url: https://free-trusty-kit.ngrok-free.app description: Local Development security: [] tags: - name: Address - name: Audit - name: Auth - name: Available scope - name: Billing Role - name: Billing Role Rate - name: Billing Role Rates - name: Billing Roles - name: Board - name: Budget - name: Budgets - name: Check In - name: Client - name: Client Project - name: Contact Info - name: Country - name: Demo Management - name: Goal - name: Goal Template - name: Goals - name: Group Notification Preferences - name: Groups description: Operations related to user groups - name: Health Metrics - name: Holiday Schemes - name: Hrosc - name: ISCO Groups - name: Integrations - name: Janitor System - name: Job Positions - name: KPIs - name: Key Result - name: Key Result Template - name: Key Results - name: Library Admin - name: Library Export - name: Library Import - name: Manager - name: Metric Period - name: Metric Template - name: Milestone - name: Nav Info - name: Newsletter - name: Notification Preferences - name: Observed Metrics - name: Org Account - name: Organizational Unit - name: Organizational Units - name: People - name: Person - name: Person Job Positions - name: Person Rate - name: Person Rates - name: Person Skills - name: Preferences - name: Public API Keys - name: Registration - name: SCM Repositories - name: Skills - name: Strategic Concept - name: Strategy - name: Stripe - name: Subscription - name: Sys Billing Role Rates - name: Sys Billing Roles - name: Sys Budgets - name: Sys Catalog - name: Sys Catalog Skill Groups - name: Sys Catalog Sync - name: Sys Check Ins - name: Sys Goals - name: Sys Job Positions - name: Sys Key Results - name: Sys Organizational Units - name: Sys Person - name: Sys Person Job Positions - name: Sys Person Rates - name: Sys Person Skills - name: Sys Public API Keys - name: Sys Skills - name: Sys Tags - name: Sys Teams - name: Sys Value Items - name: Sys Value Units - name: Tag - name: Tags - name: Team - name: Teams - name: Time zones - name: Timesheet - name: Timesheet Export - name: Timesheet Period Configuration - name: Timesheet Period Management - name: Timesheet Periods - name: Unit - name: Value Item - name: Value Item Settings - name: Value Items - name: Value Unit - name: Value Units - name: Webhooks - name: Workboards - name: Workflow - name: Workload Schemes - name: Worklog Approvals Configuration - name: Worklog Conflicts - name: Worklog Scheduler Configuration - name: Worklogs paths: /v1/public/kpis/{id}: patch: tags: - KPIs summary: Update KPI description: Applies JSON Merge Patch semantics to mutable KPI fields. operationId: updatePublicKpi parameters: - name: id in: path required: true schema: pattern: '[^\s_]\S*' type: string requestBody: description: Merge-patch payload for KPI updates. Omitted fields remain unchanged. content: application/merge-patch+json: schema: $ref: '#/components/schemas/PublicKpiUpdateDto' examples: partial update: value: targetValue: 120 clear caretakers: value: {} required: true responses: '200': description: KPI updated content: application/json: schema: $ref: '#/components/schemas/PublicKpiDto' examples: updated kpi: value: data: id: b0e8f7d1-ef61-49dd-8f91-7f2d6ab3f9f4 targetValue: 120 criteriaType: INCREASE meta: requestId: f056699e-497d-41d9-a877-d7c862de6587 timestamp: '2026-05-13T12:08:00Z' '400': description: Invalid merge-patch payload '404': description: KPI not found security: - apiKey: [] components: schemas: PublicKpiUpdateDto: type: object properties: aggregationType: enum: - AVERAGE - SUM - GEOMETRIC_MEAN - LAST_VALUE type: string nullable: true criteriaType: enum: - BASELINE - INCREASE - DECREASE - MAINTAIN - MILESTONE - PERCENTAGE type: string nullable: true initialValue: type: number nullable: true targetValue: type: number nullable: true endingPeriodType: enum: - DAY - MONTH - QUARTER - FOUR_MONTHS - SIX_MONTHS - YEAR - TWO_YEARS - THREE_YEARS - FIVE_YEARS - CUSTOM type: string nullable: true endingPeriodStartsAt: type: string allOf: - $ref: '#/components/schemas/LocalDate' nullable: true endingPeriodEndsAt: type: string allOf: - $ref: '#/components/schemas/LocalDate' nullable: true scoringType: enum: - NO_ZONES - TWO_ZONES_YES_NO - TWO_ZONES_YES_NO_ASPIRATIONAL - TWO_ZONES - TWO_ZONES_ASPIRATIONAL - TWO_ZONES_BEST_WORST - THREE_ZONES - THREE_ZONES_BEST_WORST - FOUR_ZONES_ASPIRATIONAL - FOUR_ZONES_SOFT_ORANGE - FOUR_ZONES_SOFT_GREEN - THREE_ZONES_MAINTAIN - FIVE_ZONES_MAINTAIN type: string nullable: true scoringThresholds: type: array items: type: number nullable: true caretakerIds: type: array items: type: string nullable: true autoResolveConflicts: type: boolean nullable: true PublicKpiDto: type: object properties: id: type: string metricId: type: string metricName: type: string templateId: type: string unitId: type: string dataPeriod: $ref: '#/components/schemas/DataPeriod' aggregationType: $ref: '#/components/schemas/AggregationType' criteriaType: $ref: '#/components/schemas/CriteriaType' initialValue: type: number targetValue: type: number endingPeriodType: $ref: '#/components/schemas/PeriodType' endingPeriodStartsAt: $ref: '#/components/schemas/LocalDate' endingPeriodEndsAt: $ref: '#/components/schemas/LocalDate' scoringType: $ref: '#/components/schemas/ScoringType' scoringThresholds: type: array items: type: number caretakerIds: type: array items: type: string keyResultId: type: string creationTimestamp: $ref: '#/components/schemas/Instant' updatedAt: $ref: '#/components/schemas/Instant' LocalDate: format: date type: string example: '2022-03-10' DataPeriod: enum: - DAY - MONTH - QUARTER - YEAR type: string AggregationType: enum: - AVERAGE - SUM - GEOMETRIC_MEAN - LAST_VALUE type: string CriteriaType: enum: - BASELINE - INCREASE - DECREASE - MAINTAIN - MILESTONE - PERCENTAGE type: string PeriodType: enum: - DAY - MONTH - QUARTER - FOUR_MONTHS - SIX_MONTHS - YEAR - TWO_YEARS - THREE_YEARS - FIVE_YEARS - CUSTOM type: string ScoringType: enum: - NO_ZONES - TWO_ZONES_YES_NO - TWO_ZONES_YES_NO_ASPIRATIONAL - TWO_ZONES - TWO_ZONES_ASPIRATIONAL - TWO_ZONES_BEST_WORST - THREE_ZONES - THREE_ZONES_BEST_WORST - FOUR_ZONES_ASPIRATIONAL - FOUR_ZONES_SOFT_ORANGE - FOUR_ZONES_SOFT_GREEN - THREE_ZONES_MAINTAIN - FIVE_ZONES_MAINTAIN type: string Instant: format: date-time type: string example: '2022-03-10T16:15:50Z' securitySchemes: apiKey: type: apiKey description: >- Owner-typed API key (`ORGANIZATION`, `PERSON`, `VALUE_UNIT`). Manage org-scoped lifecycle with `/v1/public-api-keys`; cross-org governance is restricted to `/v1/sys/public-api-keys`. name: X-API-Key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.