> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sagescreen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate results for a completed screen

> Calls the Python API to generate AI-scored results for a completed
screen interview. On success, stores results in post meta:

- `results_raw` — full JSON from Python
- `results_summary` — narrative summary
- `results_recommendation` — recommendation text
- `results_score_{category}` — percentage score per category
- `results_score_{category}_explanation` — explanation per category
- `results_score_{category}_quotes` — supporting quotes per category
- `overall_score` — average percentage across categories
- `results_hire` — 1 (hire) or 0 (no hire) based on threshold
- `verification_code` — 8-character alphanumeric code

Updates screen status to `ss_closed` and sets `results_finalized` timestamp.

**Errors:**
- Returns `already_exists` if results already generated (use regenerate instead)
- Returns `wrong_state` if `complete_state` is not `finished`
- Returns `no_session` if `screen_session_id` meta is missing

Registered as `wp_ajax_sagescreen_generate_results` — **login required**.




## OpenAPI

````yaml /openapi/private/specs/wp/screen.yml post /wp-admin/admin-ajax.php?action=sagescreen_generate_results
openapi: 3.1.0
info:
  title: SageScreen — Screen Module
  description: |
    Screen (interview) lifecycle management. A screen represents a single
    candidate screening session — from invite creation through completion,
    results generation, and PDF download.

    **CPT:** `ss_screen`
    **Custom statuses:** `ss_draft`, `ss_invited`, `ss_accepted`, `ss_started`,
    `ss_completed`, `ss_closed`, `ss_cancelled`, `ss_expired`

    Screens are created when candidates are invited to a sage, progress through
    the interview, and conclude with AI-generated results including category
    scores, a summary, recommendation, and a hire/no-hire determination.
  version: 1.0.0
servers:
  - url: https://{domain}/wp-json/sagescreen/v1
    description: WordPress REST API
    variables:
      domain:
        default: api.sagescreen.app
security: []
tags:
  - name: Screen – Testing
    description: Test invite and temperature check endpoints
  - name: Screen – Results
    description: Results generation, checking, regeneration, feedback, and download
  - name: Screen – Workflow
    description: Workflow progression (skip testing)
paths:
  /wp-admin/admin-ajax.php?action=sagescreen_generate_results:
    post:
      tags:
        - Screen – Results
      summary: Generate results for a completed screen
      description: >
        Calls the Python API to generate AI-scored results for a completed

        screen interview. On success, stores results in post meta:


        - `results_raw` — full JSON from Python

        - `results_summary` — narrative summary

        - `results_recommendation` — recommendation text

        - `results_score_{category}` — percentage score per category

        - `results_score_{category}_explanation` — explanation per category

        - `results_score_{category}_quotes` — supporting quotes per category

        - `overall_score` — average percentage across categories

        - `results_hire` — 1 (hire) or 0 (no hire) based on threshold

        - `verification_code` — 8-character alphanumeric code


        Updates screen status to `ss_closed` and sets `results_finalized`
        timestamp.


        **Errors:**

        - Returns `already_exists` if results already generated (use regenerate
        instead)

        - Returns `wrong_state` if `complete_state` is not `finished`

        - Returns `no_session` if `screen_session_id` meta is missing


        Registered as `wp_ajax_sagescreen_generate_results` — **login
        required**.
      operationId: ajaxGenerateResults
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/GenerateResultsRequest'
      responses:
        '200':
          description: Generation result (check `success` field)
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AjaxSuccessMessage'
                  - $ref: '#/components/schemas/AjaxErrorResponse'
              examples:
                success:
                  summary: Results generated
                  value:
                    success: true
                    data:
                      message: Results generated successfully
                alreadyExists:
                  summary: Results already exist
                  value:
                    success: false
                    data:
                      message: Results already exist. Use regenerate instead.
                wrongState:
                  summary: Screen not in finished state
                  value:
                    success: false
                    data:
                      message: >-
                        Results can only be generated for screens that were
                        completed normally (not timeout/expired/abandoned).
                noSession:
                  summary: No screen session ID
                  value:
                    success: false
                    data:
                      message: Screen session not found
                invalidScreen:
                  summary: Invalid screen
                  value:
                    success: false
                    data:
                      message: Invalid screen
                permissionDenied:
                  summary: User cannot access this screen's council
                  value:
                    success: false
                    data:
                      message: You do not have permission to access this screen
      security:
        - wpAjaxNonce: []
components:
  schemas:
    GenerateResultsRequest:
      type: object
      required:
        - action
        - nonce
        - screen_id
      properties:
        action:
          type: string
          const: sagescreen_generate_results
        nonce:
          type: string
          description: WP nonce for `sagescreen_frontend_nonce`
          examples:
            - abc123def456
        screen_id:
          type: integer
          description: Post ID of the `ss_screen`
          examples:
            - 5678
    AjaxSuccessMessage:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              examples:
                - Results generated successfully
    AjaxErrorResponse:
      type: object
      description: |
        Standard AJAX error. The `data` field is either a plain string
        or an object with a `message` field.
      properties:
        success:
          type: boolean
          const: false
        data:
          oneOf:
            - type: string
              description: Error message as plain string
              examples:
                - Security check failed
            - type: object
              properties:
                message:
                  type: string
                  examples:
                    - Screen ID is required
        message:
          type: string
          description: |
            Present on some endpoints that use `wp_send_json()` directly
            instead of `wp_send_json_error()`.
          examples:
            - Security check failed
  securitySchemes:
    wpAjaxNonce:
      type: apiKey
      in: query
      name: nonce
      description: WordPress AJAX nonce (passed as form field, verified per-action)

````