> ## 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.

# Regenerate results for a screen

> Re-calls the Python API to regenerate results for a screen that
already has results. Deletes the cached PDF before regeneration.

**Limits:** Non-admin users (`ss_admin_council` capability) can only
regenerate once per screen. Admins can regenerate unlimited times.
Returns `already_regen` error if the limit is reached.

**Errors:**
- No results to regenerate (results must exist first)
- Wrong state (complete_state must be `finished`, `expired`, or `ended`)
- Screen session not found

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




## OpenAPI

````yaml /openapi/private/specs/wp/screen.yml post /wp-admin/admin-ajax.php?action=sagescreen_regenerate_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_regenerate_results:
    post:
      tags:
        - Screen – Results
      summary: Regenerate results for a screen
      description: >
        Re-calls the Python API to regenerate results for a screen that

        already has results. Deletes the cached PDF before regeneration.


        **Limits:** Non-admin users (`ss_admin_council` capability) can only

        regenerate once per screen. Admins can regenerate unlimited times.

        Returns `already_regen` error if the limit is reached.


        **Errors:**

        - No results to regenerate (results must exist first)

        - Wrong state (complete_state must be `finished`, `expired`, or `ended`)

        - Screen session not found


        Registered as `wp_ajax_sagescreen_regenerate_results` — **login
        required**.
      operationId: ajaxRegenerateResults
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RegenerateResultsRequest'
      responses:
        '200':
          description: Regeneration result
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RegenerateResultsSuccess'
                  - $ref: '#/components/schemas/AjaxErrorResponse'
              examples:
                success:
                  summary: Results regenerated
                  value:
                    success: true
                    data:
                      message: Results regenerated successfully
                      results:
                        raw: '{"summary":"...","scores":{}}'
                        summary: >-
                          The candidate demonstrated strong communication
                          skills...
                        recommendation: Recommend for hire
                alreadyRegen:
                  summary: Already regenerated once (non-admin)
                  value:
                    success: false
                    data:
                      message: >-
                        Results have already been regenerated once. Cannot
                        regenerate again.
                noResults:
                  summary: No results to regenerate
                  value:
                    success: false
                    data:
                      message: >-
                        No results to regenerate. Results must be generated
                        first.
                wrongState:
                  summary: Screen not in valid state for regeneration
                  value:
                    success: false
                    data:
                      message: Results can only be regenerated for completed screens.
      security:
        - wpAjaxNonce: []
components:
  schemas:
    RegenerateResultsRequest:
      type: object
      required:
        - action
        - nonce
        - screen_id
      properties:
        action:
          type: string
          const: sagescreen_regenerate_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
    RegenerateResultsSuccess:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
            - message
            - results
          properties:
            message:
              type: string
              examples:
                - Results regenerated successfully
            results:
              type: object
              description: Regenerated results data
              properties:
                raw:
                  type: string
                  description: Full raw JSON results
                  examples:
                    - '{"summary":"...","scores":{},"recommendation":"..."}'
                summary:
                  type: string
                  description: Narrative summary
                  examples:
                    - The candidate demonstrated strong communication skills...
                recommendation:
                  type: string
                  description: Recommendation text
                  examples:
                    - Recommend for hire
    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)

````