{"openapi":"3.0.1","info":{"title":"Focus REST API","description":"External API for reading and writing Focus data.","version":"v1"},"servers":[{"url":"/","description":"Relative service base URL"}],"tags":[{"name":"Benefit items","description":"External APIs for benefit items."},{"name":"Benefit types","description":"External APIs for benefit types."},{"name":"Investment categories","description":"External APIs for investment categories."},{"name":"Cost items","description":"External APIs for cost items."},{"name":"Focus areas","description":"External APIs for focus areas."},{"name":"Cost subtypes","description":"External APIs for cost subtypes."},{"name":"Cost types","description":"External APIs for cost types."}],"paths":{"/focus/v1/funds/cost-item/bulk":{"post":{"tags":["Cost items"],"summary":"Bulk import cost items","description":"Creates or updates multiple cost items in a single request. Each item is identified by its internal ID or external ID. If neither is provided a new cost item is created. Returns validation errors for any items that failed processing.","operationId":"createCostItemBulk","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItemBulkRequest"}}},"required":true},"responses":{"201":{"description":"All cost items imported successfully."},"400":{"description":"One or more cost items failed validation."},"403":{"description":"Funds API access is disabled."},"500":{"description":"Internal server error."}},"security":[{"oauth2":["funds-write-scope"]},{"apiTokenAuth":[]}],"x-experimental":true}},"/focus/v1/funds/benefit-item/bulk":{"post":{"tags":["Benefit items"],"summary":"Bulk import benefit items","description":"Creates or updates multiple benefit items in a single request. Each item is identified by its internal ID or external ID. If neither is provided a new benefit item is created. Returns validation errors for any items that failed processing.","operationId":"createBenefitItemBulk","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItemBulkRequest"}}},"required":true},"responses":{"201":{"description":"All benefit items imported successfully."},"400":{"description":"One or more benefit items failed validation."},"403":{"description":"Funds API access is disabled."},"500":{"description":"Internal server error."}},"security":[{"oauth2":["funds-write-scope"]},{"apiTokenAuth":[]}],"x-experimental":true}},"/focus/v1/focus-areas":{"get":{"tags":["Focus areas"],"summary":"Get focus areas","description":"Returns a paginated list of focus areas with optional filtering.","operationId":"getFocusAreas","parameters":[{"name":"limit","in":"query","description":"Maximum number of focus areas to return in a page.","required":false,"schema":{"type":"string","default":""}},{"name":"cursor","in":"query","description":"Pagination cursor for the next page.","required":false,"schema":{"type":"string","default":""}},{"name":"nameContains","in":"query","description":"Case-insensitive filter for focus area names.","required":false,"schema":{"type":"string","default":""}},{"name":"externalId","in":"query","description":"External ID to filter by.","required":false,"schema":{"type":"string","default":""}},{"name":"parentId","in":"query","description":"Parent focus area ID to filter by. Returns all focus areas under the parent.","required":false,"schema":{"type":"string","default":""}},{"name":"sort","in":"query","description":"Sort directives to apply to the results.","required":false,"schema":{"type":"string","default":""},"example":"+name"}],"responses":{"200":{"description":"Focus areas returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"403":{"description":"Focus areas API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"501":{"description":"Endpoint is not implemented yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}}},"security":[{"oauth2":["focus-areas-read-scope"]},{"apiTokenAuth":[]}]},"post":{"tags":["Focus areas"],"summary":"Create a focus area","description":"Creates a new focus area with the provided details. Status is automatically set to PENDING. Target date and target date type are not set on create, and draft defaults to false. If parent focus area is omitted, the new focus area is created as top-level. When owner is omitted, the authenticated user is used as creator and owner.","operationId":"createFocusArea","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFocusAreaRequest"}}},"required":true},"responses":{"201":{"description":"Focus area created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"400":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"401":{"description":"Caller is not authorized to create a focus area.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"403":{"description":"Focus areas API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"404":{"description":"One or more of the request parameters not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}}},"security":[{"oauth2":["focus-areas-write-scope"]},{"apiTokenAuth":[]}]}},"/focus/v1/funds/cost-item/{id}":{"get":{"tags":["Cost items"],"summary":"Get a cost item","description":"Returns cost item details by cost item ID.","operationId":"getCostItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cost item returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}},"400":{"description":"Invalid cost item ID request parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}},"403":{"description":"Funds API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}},"404":{"description":"Cost item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}}},"security":[{"oauth2":["funds-read-scope"]},{"apiTokenAuth":[]}],"x-experimental":true},"delete":{"tags":["Cost items"],"summary":"Delete a cost item","description":"Deletes the specified cost item. This action is irreversible.","operationId":"deleteCostItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Cost item deleted successfully."},"400":{"description":"Invalid cost item ID request parameter."},"403":{"description":"Funds API access is disabled."},"404":{"description":"Cost item not found."},"500":{"description":"Internal server error."}},"security":[{"oauth2":["funds-write-scope"]},{"apiTokenAuth":[]}],"x-experimental":true},"patch":{"tags":["Cost items"],"summary":"Update a cost item","description":"Updates the details of the specified cost item. The `updateMask` query parameter specifies which fields to update; supported fields are `externalCostItemId`. Fields not listed in `updateMask` are not modified. Fields listed in `updateMask` but omitted from the request body or set to `null` are cleared.","operationId":"updateCostItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"updateMask","in":"query","description":"Comma-separated list of fields to update. Supported values: `externalCostItemId`.","required":true,"schema":{"type":"string","default":""}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCostItemRequest"}}},"required":true},"responses":{"200":{"description":"Cost item updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}},"400":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}},"403":{"description":"Funds API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}},"404":{"description":"Cost item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}},"409":{"description":"External ID conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostItem"}}}}},"security":[{"oauth2":["funds-write-scope"]},{"apiTokenAuth":[]}],"x-experimental":true}},"/focus/v1/funds/benefit-item/{id}":{"get":{"tags":["Benefit items"],"summary":"Get a benefit item","description":"Returns benefit item details by benefit item ID.","operationId":"getBenefitItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Benefit item returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}},"400":{"description":"Invalid benefit item ID request parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}},"403":{"description":"Funds API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}},"404":{"description":"Benefit item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}}},"security":[{"oauth2":["funds-read-scope"]},{"apiTokenAuth":[]}],"x-experimental":true},"delete":{"tags":["Benefit items"],"summary":"Delete a benefit item","description":"Deletes the specified benefit item. This action is irreversible.","operationId":"deleteBenefitItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Benefit item deleted successfully."},"400":{"description":"Invalid benefit item ID request parameter."},"403":{"description":"Funds API access is disabled."},"404":{"description":"Benefit item not found."},"500":{"description":"Internal server error."}},"security":[{"oauth2":["funds-write-scope"]},{"apiTokenAuth":[]}],"x-experimental":true},"patch":{"tags":["Benefit items"],"summary":"Update a benefit item","description":"Updates the details of the specified benefit item. The `updateMask` query parameter specifies which fields to update; supported fields are `externalId`. Fields not listed in `updateMask` are not modified. Fields listed in `updateMask` but omitted from the request body or set to `null` are cleared.","operationId":"updateBenefitItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"updateMask","in":"query","description":"Comma-separated list of fields to update. Supported values: `externalId`.","required":true,"schema":{"type":"string","default":""}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBenefitItemRequest"}}},"required":true},"responses":{"200":{"description":"Benefit item updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}},"400":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}},"403":{"description":"Funds API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}},"404":{"description":"Benefit item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}},"409":{"description":"External ID conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenefitItem"}}}}},"security":[{"oauth2":["funds-write-scope"]},{"apiTokenAuth":[]}],"x-experimental":true}},"/focus/v1/focus-areas/{focusAreaId}":{"get":{"tags":["Focus areas"],"summary":"Get a focus area","description":"Returns focus area details by focus area ID.","operationId":"getFocusAreaById","parameters":[{"name":"focusAreaId","in":"path","description":"The ID of the focus area.","required":true,"schema":{"type":"string","default":""}}],"responses":{"200":{"description":"Focus area returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"400":{"description":"Invalid Focus area ID request parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"403":{"description":"Focus areas API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"404":{"description":"Focus area not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}}},"security":[{"oauth2":["focus-areas-read-scope"]},{"apiTokenAuth":[]}]},"delete":{"tags":["Focus areas"],"summary":"Delete a focus area","description":"Deletes the specified focus area. This action is irreversible and will re-parent all child focus areas to the parent of the deleted focus area, or as parentless if the deleted focus area is a parent.","operationId":"deleteFocusArea","parameters":[{"name":"focusAreaId","in":"path","description":"The ID of the focus area to delete.","required":true,"schema":{"type":"string","default":""}}],"responses":{"204":{"description":"Focus area deleted successfully."},"400":{"description":"Invalid focus area ID request parameter."},"401":{"description":"Caller is not authorized to delete a focus area."},"403":{"description":"Focus areas API access is disabled."},"404":{"description":"Focus area to delete not found."},"500":{"description":"Internal server error."}},"security":[{"oauth2":["focus-areas-write-scope"]},{"apiTokenAuth":[]}]},"patch":{"tags":["Focus areas"],"summary":"Update a focus area","description":"Updates the details of the specified focus area. The `updateMask` query parameter specifies which fields to update; supported fields are `name`, `ownerId`, `externalId`, and `about`. Fields not listed in `updateMask` are not modified. Fields listed in `updateMask` but omitted from the request body or set to `null` are cleared; clearing a required field is not allowed and will result in a 400 response.","operationId":"updateFocusArea","parameters":[{"name":"focusAreaId","in":"path","description":"The ID of the focus area to update.","required":true,"schema":{"type":"string","default":""}},{"name":"updateMask","in":"query","description":"Comma-separated list of fields to update. Supported fields: `name`, `ownerId`, `externalId`, `about`.","required":true,"schema":{"type":"string","default":""},"example":"name,about"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFocusAreaRequest"}}},"required":true},"responses":{"200":{"description":"Focus area updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"400":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"401":{"description":"Caller is not authorized to update a focus area.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"403":{"description":"Focus areas API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"404":{"description":"One or more of the request parameters not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusArea"}}}}},"security":[{"oauth2":["focus-areas-write-scope"]},{"apiTokenAuth":[]}]}},"/focus/v1/funds/investment-category":{"get":{"tags":["Investment categories"],"summary":"Get investment categories","description":"Returns all available investment categories.","operationId":"getInvestmentCategories","responses":{"200":{"description":"Investment categories returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestmentCategory"}}}},"403":{"description":"Funds API access is disabled.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvestmentCategory"}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvestmentCategory"}}}}}},"security":[{"oauth2":["funds-read-scope"]},{"apiTokenAuth":[]}],"x-experimental":true}},"/focus/v1/funds/cost-type":{"get":{"tags":["Cost types"],"summary":"Get cost types","description":"Returns all available cost types.","operationId":"getCostTypes","responses":{"200":{"description":"Cost types returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"403":{"description":"Funds API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}}},"security":[{"oauth2":["funds-read-scope"]},{"apiTokenAuth":[]}],"x-experimental":true}},"/focus/v1/funds/cost-subtype":{"get":{"tags":["Cost subtypes"],"summary":"Get cost subtypes","description":"Returns all available cost subtypes.","operationId":"getCostSubtypes","responses":{"200":{"description":"Cost subtypes returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"403":{"description":"Funds API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}}},"security":[{"oauth2":["funds-read-scope"]},{"apiTokenAuth":[]}],"x-experimental":true}},"/focus/v1/funds/cost-item":{"get":{"tags":["Cost items"],"summary":"Get cost items","description":"Returns a paginated list of cost items with optional filtering.","operationId":"getCostItems","parameters":[{"name":"externalId","in":"query","description":"Filter by external cost item ID. Returns at most one result.","required":false,"schema":{"type":"string","default":""}}],"responses":{"200":{"description":"Cost items returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"403":{"description":"Funds API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}}},"security":[{"oauth2":["funds-read-scope"]},{"apiTokenAuth":[]}],"x-experimental":true}},"/focus/v1/funds/benefit-type":{"get":{"tags":["Benefit types"],"summary":"Get benefit types","description":"Returns all available benefit types.","operationId":"getBenefitTypes","responses":{"200":{"description":"Benefit types returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"403":{"description":"Funds API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}}},"security":[{"oauth2":["funds-read-scope"]},{"apiTokenAuth":[]}],"x-experimental":true}},"/focus/v1/funds/benefit-item":{"get":{"tags":["Benefit items"],"summary":"Get benefit items","description":"Returns a paginated list of benefit items with optional filtering.","operationId":"getBenefitItems","parameters":[{"name":"externalId","in":"query","description":"Filter by external benefit item ID. Returns at most one result.","required":false,"schema":{"type":"string","default":""}}],"responses":{"200":{"description":"Benefit items returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"403":{"description":"Funds API access is disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}}},"security":[{"oauth2":["funds-read-scope"]},{"apiTokenAuth":[]}],"x-experimental":true}}},"components":{"schemas":{"CostItemBulkRequest":{"required":["items"],"type":"object","properties":{"items":{"minItems":1,"type":"array","properties":{"empty":{"type":"boolean"},"first":{"$ref":"#/components/schemas/CostItemRequest"},"last":{"$ref":"#/components/schemas/CostItemRequest"}},"description":"The list of cost items to create or update. Must not be empty.","items":{"$ref":"#/components/schemas/CostItemRequest"},"default":null}},"description":"Request body for bulk cost item import.","default":null},"CostItemRequest":{"required":["name"],"type":"object","properties":{"focusAreaId":{"type":"string","format":"uuid"},"focusAreaExternalId":{"type":"string"},"costItemId":{"type":"string","format":"uuid"},"costItemExternalId":{"type":"string"},"name":{"type":"string"},"costType":{"type":"string"},"costSubtypeKey":{"type":"string"},"expenditureType":{"$ref":"#/components/schemas/ExpenditureType"},"investmentCategoryKey":{"type":"string"},"costPeriodValues":{"type":"array","properties":{"empty":{"type":"boolean"},"first":{"$ref":"#/components/schemas/CostPeriodValueRequest"},"last":{"$ref":"#/components/schemas/CostPeriodValueRequest"}},"items":{"$ref":"#/components/schemas/CostPeriodValueRequest"}}}},"CostPeriodValueRequest":{"required":["financialVersionType"],"type":"object","properties":{"financialVersionType":{"type":"string","enum":["ACTUAL","FORECAST","BASELINE"]},"timePeriodToAmount":{"type":"object","properties":{"empty":{"type":"boolean"}},"additionalProperties":{"type":"number"}}}},"ExpenditureType":{"required":["displayName","id","key","name","order"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"order":{"type":"integer","format":"int32"},"key":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"}}},"BenefitItemBulkRequest":{"required":["items"],"type":"object","properties":{"items":{"minItems":1,"type":"array","properties":{"empty":{"type":"boolean"},"first":{"$ref":"#/components/schemas/BenefitItemRequest"},"last":{"$ref":"#/components/schemas/BenefitItemRequest"}},"description":"The list of benefit items to create or update. Must not be empty.","items":{"$ref":"#/components/schemas/BenefitItemRequest"},"default":null}},"description":"Request body for bulk benefit item import.","default":null},"BenefitItemRequest":{"required":["name"],"type":"object","properties":{"focusAreaId":{"type":"string","format":"uuid"},"focusAreaExternalId":{"type":"string"},"benefitItemId":{"type":"string","format":"uuid"},"benefitItemExternalId":{"type":"string"},"benefitTypeKey":{"type":"string"},"name":{"type":"string"},"benefitPeriodValues":{"type":"array","properties":{"empty":{"type":"boolean"},"first":{"$ref":"#/components/schemas/BenefitPeriodValueRequest"},"last":{"$ref":"#/components/schemas/BenefitPeriodValueRequest"}},"items":{"$ref":"#/components/schemas/BenefitPeriodValueRequest"}}}},"BenefitPeriodValueRequest":{"required":["financialVersionType"],"type":"object","properties":{"financialVersionType":{"type":"string","enum":["ACTUAL","FORECAST","BASELINE"]},"timePeriodToAmount":{"type":"object","properties":{"empty":{"type":"boolean"}},"additionalProperties":{"type":"number"}}}},"CreateFocusAreaRequest":{"required":["focusAreaTypeId","name"],"type":"object","properties":{"name":{"type":"string","description":"The name of the focus area.","default":""},"focusAreaTypeId":{"type":"string","description":"The focus area type ID indicating hierarchy level.","format":"uuid"},"externalId":{"type":"string","description":"Optional external identifier for cross-system correlation.","nullable":true,"default":""},"parentFocusAreaId":{"type":"string","description":"Optional parent focus area id. If omitted, the new focus area is top-level.","format":"uuid","nullable":true},"ownerId":{"type":"string","description":"Optional owner user id. If omitted, the authenticated user is used.","nullable":true,"default":""}},"description":"Create focus area request. Status is set to PENDING, draft is set to false, and target date fields are not set upon creation.","default":null},"FocusArea":{"required":["createdDate","focusAreaType","id","name","owner","path","status","updatedDate"],"type":"object","properties":{"id":{"type":"string","description":"The ID of the focus area.","default":""},"parent":{"$ref":"#/components/schemas/FocusAreaParent"},"name":{"type":"string","description":"The name of the focus area.","default":""},"externalId":{"type":"string","description":"Client-provided external identifier for cross-system correlation.","nullable":true,"default":""},"about":{"type":"string","description":"Content describing what a focus area is about.","nullable":true,"default":""},"createdDate":{"type":"string","description":"The date the focus area was created.","format":"date-time"},"updatedDate":{"type":"string","description":"The date any field on the focus area was last updated.","format":"date-time"},"owner":{"$ref":"#/components/schemas/FocusAreaOwner"},"focusAreaType":{"$ref":"#/components/schemas/FocusAreaType"},"targetDate":{"type":"string","description":"The target delivery date of the focus area.","format":"date-time","nullable":true},"path":{"type":"array","properties":{"empty":{"type":"boolean"},"first":{"$ref":"#/components/schemas/FocusAreaPathItem"},"last":{"$ref":"#/components/schemas/FocusAreaPathItem"}},"description":"The ancestor path of the focus area ordered from root to immediate parent. The current focus area is not included. Each item's index is a zero-based position in this root-to-parent order.","items":{"$ref":"#/components/schemas/FocusAreaPathItem"},"default":null},"status":{"$ref":"#/components/schemas/FocusAreaStatus"}},"description":"A Focus Area.","default":null},"FocusAreaOwner":{"required":["id"],"type":"object","properties":{"id":{"type":"string","description":"The owner user ID.","default":""},"name":{"type":"string","description":"Display name of the owner when available.","nullable":true,"default":""}},"description":"Owner details for a focus area.","default":null},"FocusAreaParent":{"required":["id"],"type":"object","properties":{"id":{"type":"string","description":"The ID of the parent focus area.","default":""}},"description":"The parent focus area of the current focus area.","nullable":true,"default":null},"FocusAreaPathItem":{"required":["id","index"],"type":"object","properties":{"id":{"type":"string","description":"The ID of the ancestor focus area.","default":""},"index":{"type":"integer","description":"Zero-based position in the path order where 0 is root and the highest index is the immediate parent.","format":"int32"}},"description":"A single ancestor in the focus area path, ordered from root to immediate parent.","default":null},"FocusAreaStatus":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"The status ID.","default":""},"name":{"type":"string","description":"The status name.","default":""}},"description":"Focus area status details.","default":null},"FocusAreaType":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"The ID of the focus area type.","default":""},"name":{"type":"string","description":"The name of the focus area type.","default":""}},"description":"Focus area type details.","default":null},"UpdateCostItemRequest":{"type":"object","description":"Update cost item request.","default":null},"CostItem":{"required":["costItemId","focusAreaId","name"],"type":"object","properties":{"costItemId":{"type":"string","description":"The ID of the cost item.","format":"uuid"},"externalCostItemId":{"type":"string","description":"Client-provided external identifier for cross-system correlation.","nullable":true,"default":""},"focusAreaId":{"type":"string","description":"The ID of the focus area this cost item belongs to.","format":"uuid"},"costType":{"type":"string","description":"The cost type key.","nullable":true,"default":""},"costSubtypeId":{"type":"string","description":"The cost subtype ID.","format":"uuid","nullable":true},"expenditureType":{"type":"string","description":"The expenditure type (CAPEX or OPEX).","nullable":true,"default":""},"investmentCategoryId":{"type":"string","description":"The investment category ID.","format":"uuid","nullable":true},"name":{"type":"string","description":"The name of the cost item.","default":""}},"description":"A cost item.","default":null},"UpdateBenefitItemRequest":{"type":"object","properties":{"externalId":{"type":"string","description":"The external benefit item ID. Set to null to clear.","default":""}},"description":"Update benefit item request.","default":null},"BenefitItem":{"required":["benefitItemId","focusAreaId","name"],"type":"object","properties":{"benefitItemId":{"type":"string","description":"The ID of the benefit item.","format":"uuid"},"externalBenefitItemId":{"type":"string","description":"Client-provided external identifier for cross-system correlation.","nullable":true,"default":""},"focusAreaId":{"type":"string","description":"The ID of the focus area this benefit item belongs to.","format":"uuid"},"name":{"type":"string","description":"The name of the benefit item.","default":""}},"description":"A benefit item.","default":null},"UpdateFocusAreaRequest":{"type":"object","properties":{"name":{"type":"string","description":"The name of the focus area.","nullable":true,"default":""},"ownerId":{"type":"string","description":"The focus area owner user id.","nullable":true,"default":""},"externalId":{"type":"string","description":"External identifier for cross-system correlation.","nullable":true,"default":""},"about":{"type":"string","description":"The about content.","nullable":true,"default":""}},"description":"Update focus area request.","default":null},"InvestmentCategory":{"required":["investmentCategoryId","key"],"type":"object","properties":{"investmentCategoryId":{"type":"string","description":"The ID of the investment category.","format":"uuid"},"key":{"type":"string","description":"The investment category key.","default":""}},"description":"An investment category.","default":null},"PaginatedResponse":{"required":["last","totalCount","values"],"type":"object","properties":{"values":{"type":"array","properties":{"empty":{"type":"boolean"},"first":{"type":"object"},"last":{"type":"object"}},"description":"The items in this page.","items":{"type":"object","description":"The items in this page.","default":null},"default":null},"cursor":{"type":"string","description":"Cursor used to fetch this page.","nullable":true,"default":""},"last":{"type":"boolean","description":"Whether this is the last page.","default":false},"totalCount":{"type":"integer","description":"Total count of items.","format":"int32"},"nextPageCursor":{"type":"string","description":"Cursor to request the next page when available.","nullable":true,"default":""}},"description":"Paginated REST response.","default":null}},"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://auth.atlassian.com/oauth/token","scopes":{"focus-areas-read-scope":"Read Focus Area data","focus-areas-write-scope":"Write Focus Area data","funds-read-scope":"Read Funds data","funds-write-scope":"Write Funds data"}}}},"apiTokenAuth":{"type":"http","description":"API token authentication via HTTP Basic (email:api_token). Scoped API tokens are validated using the same scope ids as OAuth.","scheme":"basic"}}},"x-atlassian-narrative":{"documents":[{"title":"About","anchor":"about","body":"This is the reference for the Focus REST API.\nThe REST API enables you to interact with [Focus](/cloud/focus/) programmatically.\nUse this API for scripting interactions with Focus and sending data from external tools.\nThis page documents the REST resources available in Focus, including the HTTP response codes and example requests and responses."},{"title":"Version","anchor":"version","body":"This documentation is for version 1 of the Focus REST API."},{"title":"Base paths","anchor":"base-paths","body":"Focus REST API v1 resources are available through the following gateway paths:\n* `https://your-domain.atlassian.net/gateway/api/focus/v1/focus-areas`\n* `https://api.atlassian.com/focus/cloud/{cloudId}/v1/focus-areas`\n\nUse the first path for site-domain access. Use the second path for cloud-id based access."},{"title":"Authentication","anchor":"authentication","body":"The Focus REST API supports the following authentication methods:\n### Atlassian API token (Basic auth)\nUse this method when calling through your Atlassian site domain and gateway path:\n```\ncurl --request GET \\\n  --url 'https://your-domain.atlassian.net/gateway/api/focus/v1/focus-areas' \\\n  --user 'email@example.com:<api_token>' \\\n  --header 'Accept: application/json'\n```\n### OAuth 2.0 bearer token\nUse this method with an OAuth 2.0 access token in the `Authorization` header:\n```\ncurl --request GET \\\n  --url 'https://api.atlassian.com/focus/cloud/<cloud_id>/v1/focus-areas' \\\n  --header 'Authorization: Bearer <access_token>' \\\n  --header 'Accept: application/json'\n```\n### Atlassian session authentication\nBrowser-based requests from authenticated Atlassian sessions are also supported on site-domain gateway paths.\nOAuth 2.0 scopes used by this API include:\n* `focus-areas-read-scope` for read operations\n* `focus-areas-write-scope` for write operations\n### Generate an API token (Basic auth method)\nAPI token authentication uses HTTP Basic auth with your Atlassian account email and API token.\n1. Generate an API token for your Atlassian account: https://id.atlassian.com/manage/api-tokens\n2. Use `email@example.com:<api_token>` with Basic auth (for example via `--user` in cURL), or build the equivalent `Authorization: Basic ...` header."},{"title":"Authorization","anchor":"authorization","body":"Authorization is enforced based on the authenticated principal and granted scopes/permissions for the requested operation.\nFor OAuth 2.0 and API token calls through `api.atlassian.com`, access is evaluated against the target cloud site (`cloudId`)."},{"title":"Status codes","anchor":"status-code","body":"The Focus REST API uses the [standard HTTP status codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).\n\nResponses that return an error status code also return a response body, similar to this:\n```json\n{\n  \"errors\": [\n    {\n      \"type\": \"FORMAT_INVALID\",\n      \"message\": \"Field [name] is invalid.\"\n    }\n  ]\n}\n```"}]}}