Performance goal suggestions¶

AI Hub Main API on this instance: Swagger · ReDoc · Live OpenAPI JSON

Main HTTP reference

Two endpoints help employees prepare SMART performance goals (Specific, Measurable, Achievable, Relevant, Time-bound) and the key results that measure them during a review. Suggestions are never saved: SmartMobility displays them, lets the user select and edit them, and stores only the goals and key results the user explicitly adds. Existing goal and key result editing permissions are enforced by SmartMobility before it calls AIHub.

Both endpoints require the standard API key. When the key is bound to a client, clientId must match it (403 otherwise). Each request makes one call with the large LLM profile and a strict structured output, so OpenAI-compatible and Anthropic providers return the same shape. Generated text uses the requested BCP 47 locale.

User workflow¶

1. In the Past goals or Future goals tab, the user opens SMART goals suggestions and SmartMobility calls the goal endpoint.
2. The modal lists the suggested titles and descriptions. To show more suggestions, SmartMobility calls the endpoint again with the titles already displayed in previouslySuggestedTitles.
3. For each selected goal, SmartMobility opens the goal form prefilled with the title, description and target date, and calls the key result endpoint to fill its key results.
4. In the goal form, AI suggestions calls the key result endpoint for the current goal. The goal description is required for this call. The button is unavailable once the goal has four key results.

Suggest goals¶

POST /api/v1/performance-goals/suggestions¶

The employee profile is read from the tenant user record: current job, job family, skills, skill gaps and professional experiences. Identity and contact data are never sent to the model. The request supplies the employee's goals, because AIHub does not store goals:

Each suggestion has a title (100 characters at most), a description (1,000 at most), a rationale addressed to the employee and a targetDate. Target dates are after the current UTC day and never after periodEndDate; a later model date is bounded to it. Without a review period, target dates stay within one year. A periodEndDate that is not in the future returns 422 period_already_ended.

Suggestions that repeat an existing, deleted or already displayed title are removed, case-insensitively. The model is also instructed not to rephrase those goals or close variants of refused ones.

Suggest key results¶

POST /api/v1/performance-goals/key-results/suggestions¶

The request carries the goal (title and required description, optional targetDate), its existingKeyResults and the deletedKeyResults removed from it. An optional userId adds the employee's current job and job family as context; an unknown or inactive user returns 404 user_not_found.

A goal holds at most four key results. The endpoint returns at most the goal's remaining capacity, further limited by the optional maxKeyResults (one to four). A request with four existing key results is rejected with 422.

Every suggestion uses a supported measurement type and only the configuration that belongs to it:

The model infers a currency only when the goal states or clearly implies it; otherwise currency is null and the user selects it. targetValue is an editable proposed target when a realistic scale is available, or null when unknown facts prevent a grounded suggestion.

The suggested title and description preserve the goal's measurement population and period. For rates, the denominator contains all eligible items and the numerator contains those meeting the measured condition. The model must not silently narrow the denominator to completed or successful items unless the goal defines that scope. For example, when an objective explicitly covers all SQL queries changed during a period, review before merge is the qualifying condition; it does not restrict the population to queries already merged.

The numerator states the success condition explicitly. SQL correctness counts queries whose outputs match the expected results, divided by all queries in the current production workload and multiplied by 100. Counting queries merely checked measures validation coverage instead. Ambiguous wording such as "queries validated" alone is insufficient to define that success condition.

For quantitative measures, the generation prompt distinguishes two meanings of startValue:

• Counts or rates of results achieved from the start of the goal use 0 as a tracking initialization. For rates, this is a product convention, not a historical observation or a mathematical claim about a ratio with no data.
• Measures of an existing level use its stated current value, or null if that value is unknown. Being a percentage does not by itself justify starting at 0.

For example, reviewing 95% of SQL queries changed during a new goal period uses startValue: 0. Raising an existing SQL query correctness rate to 95% uses startValue: null when its current rate is unknown. The employee reviews these suggestions; neither example asserts that the target has already been achieved. Boolean measures keep both values null. Titles are limited to 100 characters and descriptions to 500, matching the key result form.

Existing and deleted key results are excluded case-insensitively, and the model is instructed not to suggest the same measure under different wording.

Empty results and errors¶

An empty result is a successful response with a reason that SmartMobility can display while keeping manual creation available:

noSuggestionReason is null whenever suggestions are returned. Invalid suggestions, such as an overlong title or a target date in the past, are discarded individually; when every generated suggestion is unusable, or the model returns no suggestion without a reason, the endpoint returns 502 invalid_model_output and the user can retry. Other failures return 404 unknown_database, 404 user_not_found, 422 for invalid or oversized context, 504 generation_timed_out or a sanitized 500 generation_failed.