Replace Cost Category Keyword Aliases

PUT 
/api/cost-category-keyword-aliases

Replace the full set of keyword aliases for a single cost category. Idempotent — the repository diffs the supplied list against the existing rows: removes keywords not in the new list, inserts new ones. Default-flagged keywords (seeded by migration) are preserved if they remain in the new list, or removed if dropped. Keywords are normalized to lowercase + trimmed; duplicates are deduped server-side.

Required scope: purchase-orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Request body:

Field	Type	Required	Notes
cost_category_id	integer	yes	Must exist in cost_categories.
keywords	array	yes (present)	Each keyword: string, min 2 / max 100 chars. May be empty array to clear all keywords.

Response 200:

{
  "data": {
    "cost_category_id": 4,
    "keywords": ["freight", "shipping", "fuel surcharge", "airfreight"]
  },
  "message": "Keyword aliases updated."
}

Response 422 (validation):

{
  "message": "The cost category id field is required.",
  "errors": {
    "cost_category_id": ["The cost category id field is required."],
    "keywords.0": ["Each keyword must be at least 2 characters."]
  }
}

Request

Responses

200

Successful response

401

Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.

403

Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.

422

Validation failed — the body is a field → messages map (Laravel shape) or the platform envelope with a stable machine-readable code. Fix the payload and resubmit.

429

Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.