> ## Documentation Index > Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt > Use this file to discover all available pages before exploring further. # Retire Quote Rating > Retires a saved quote's current rating for one rating workflow, once that workflow has changed since the rating and nothing else makes the rating out of date. Only the rating stops being current: nothing is saved to the quote, which keeps everything the rating wrote, `fullTermPricingInfo` included. With no current rating, the workflow is not checked for staleness: the quote's rating reads Not Checked, and [Bind Quote](/api-reference/field-model-policy-transactions/bind-quote) and [Check Bind Conditions](/api-reference/field-model-policy-validation/check-bind-conditions) raise no out-of-date advisory or `409 quote-rating-out-of-date` for it, until the quote is rated again in the app or with [Rate Saved Quote by Id](/api-reference/field-model-rating/rate-saved-quote-by-id) and `saveToQuote: true`. [Clear Quote Rating](/api-reference/policy-invoicing/clear-quote-rating), which refuses a rating made under an earlier version of its workflow, then clears the quote's selected workflow. Staff use it when a workflow changes in a way that leaves the ratings made under it standing, such as taking the pricing stage out of a workflow when a company's quote price becomes a calculation: those ratings would otherwise read Rating setup changed although nothing they priced changed. The rating's freshness is judged as Bind Quote judges it. A rating that is out of date for something besides its workflow's change (an input it read, the term or the policy version changed, or one of its raters has a newer version) keeps that warning: it stays current, and the response says `outOfDate` and names what `changed`. Every change to a workflow's setup reads as one change, so a rating an earlier setup change had already put out of date is retired too, and while the rater catalog cannot be read, a newer rater version goes unseen. A rating made under the workflow as it is configured now stays current (`workflowUnchanged`), and a quote with no current rating for the workflow answers `noCurrentRating`. None of these changes anything, so the request is safe to send again. **Refusals.** A bound or cancelled quote returns `409`. Nothing changes on a refusal. **Required permission:** none — staff level `staff` (a staff user's own Bearer token or a verified platform service identity); API keys are rejected. ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/quotes/{quoteId}/rating/retire openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://go.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/companies/{companyId}/quotes/{quoteId}/rating/retire: post: tags: - Field Model Rating summary: Retire Quote Rating description: > Retires a saved quote's current rating for one rating workflow, once that workflow has changed since the rating and nothing else makes the rating out of date. Only the rating stops being current: nothing is saved to the quote, which keeps everything the rating wrote, `fullTermPricingInfo` included. With no current rating, the workflow is not checked for staleness: the quote's rating reads Not Checked, and [Bind Quote](/api-reference/field-model-policy-transactions/bind-quote) and [Check Bind Conditions](/api-reference/field-model-policy-validation/check-bind-conditions) raise no out-of-date advisory or `409 quote-rating-out-of-date` for it, until the quote is rated again in the app or with [Rate Saved Quote by Id](/api-reference/field-model-rating/rate-saved-quote-by-id) and `saveToQuote: true`. [Clear Quote Rating](/api-reference/policy-invoicing/clear-quote-rating), which refuses a rating made under an earlier version of its workflow, then clears the quote's selected workflow. Staff use it when a workflow changes in a way that leaves the ratings made under it standing, such as taking the pricing stage out of a workflow when a company's quote price becomes a calculation: those ratings would otherwise read Rating setup changed although nothing they priced changed. The rating's freshness is judged as Bind Quote judges it. A rating that is out of date for something besides its workflow's change (an input it read, the term or the policy version changed, or one of its raters has a newer version) keeps that warning: it stays current, and the response says `outOfDate` and names what `changed`. Every change to a workflow's setup reads as one change, so a rating an earlier setup change had already put out of date is retired too, and while the rater catalog cannot be read, a newer rater version goes unseen. A rating made under the workflow as it is configured now stays current (`workflowUnchanged`), and a quote with no current rating for the workflow answers `noCurrentRating`. None of these changes anything, so the request is safe to send again. **Refusals.** A bound or cancelled quote returns `409`. Nothing changes on a refusal. **Required permission:** none — staff level `staff` (a staff user's own Bearer token or a verified platform service identity); API keys are rejected. operationId: retireQuoteRating parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/quoteIdPath' requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - ratingWorkflowName properties: ratingWorkflowName: type: string minLength: 1 description: >- The configured name of the workflow whose current rating to retire examples: retire: summary: Retire the GL Rating workflow's rating value: ratingWorkflowName: GL Rating responses: '200': description: >- The workflow's current rating is retired, or was left as it is. The quote itself is unchanged either way. content: application/json: schema: type: object additionalProperties: false required: - quoteId - ratingWorkflowName - outcome properties: quoteId: type: string format: uuid description: The quote ratingWorkflowName: type: string description: The workflow named in the request outcome: type: string enum: - retired - noCurrentRating - workflowUnchanged - outOfDate description: >- `retired`: the rating was made under an earlier version of the workflow, or under a workflow no longer configured, or recorded nothing to judge it by, and nothing else makes it out of date; it is no longer current. `noCurrentRating`: the quote has no current rating for the workflow. `workflowUnchanged`: the rating was made under the workflow as it is configured now, so it stays current. `outOfDate`: the workflow changed since the rating, but the rating is out of date for `changed` too, so it stays current and keeps that warning. ratingRunId: type: string format: uuid description: >- The rating retired, or the one that stays current. Absent with `noCurrentRating`. changed: type: array items: type: string description: >- `outOfDate` only: what besides the workflow changed since the rating. Each entry is the path of an input it read (such as `quote.excessLiabilityPremium`), `window` (the term), `policyVersion`, or `raterVersion`. examples: retired: summary: The rating is retired value: quoteId: 550e8400-e29b-41d4-a716-446655440002 ratingWorkflowName: GL Rating outcome: retired ratingRunId: 550e8400-e29b-41d4-a716-446655440030 workflowUnchanged: summary: The rating still describes its workflow, and stays current value: quoteId: 550e8400-e29b-41d4-a716-446655440002 ratingWorkflowName: GL Rating outcome: workflowUnchanged ratingRunId: 550e8400-e29b-41d4-a716-446655440030 outOfDate: summary: >- The rating is out of date for an edited input too, and stays current value: quoteId: 550e8400-e29b-41d4-a716-446655440002 ratingWorkflowName: GL Rating outcome: outOfDate ratingRunId: 550e8400-e29b-41d4-a716-446655440030 changed: - quote.excessLiabilityPremium noCurrentRating: summary: The quote has no current rating for the workflow value: quoteId: 550e8400-e29b-41d4-a716-446655440002 ratingWorkflowName: GL Rating outcome: noCurrentRating '400': description: >- The quote id is not a uuid, `ratingWorkflowName` is missing or empty, or the body has another key, `quoteId` included. Nothing changes. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingWorkflow: summary: No workflow named value: error: code: VALIDATION_ERROR message: >- ratingWorkflowName: Invalid input: expected string, received undefined userMessages: - >- ratingWorkflowName: Invalid input: expected string, received undefined '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: No quote with the given id exists for this company. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: quoteNotFound: summary: Quote not found value: error: code: NotFoundError message: Quote not found userMessages: - Quote not found '409': description: >- The quote's rating can no longer change. A `bound` quote returns `QuoteBoundImmutable` with `referencingPolicy`, the policy it is bound to; a `cancelled` quote returns `QuoteNotEditable`. Nothing changes. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - QuoteBoundImmutable - QuoteNotEditable description: Machine-readable error code message: type: string description: Human-readable error message userMessages: type: array items: type: string referencingPolicy: type: string format: uuid nullable: true description: >- `QuoteBoundImmutable` only: the policy the quote is bound to. examples: quoteBound: summary: The quote is bound value: error: code: QuoteBoundImmutable message: >- Quote 550e8400-e29b-41d4-a716-446655440002 is bound to policy 550e8400-e29b-41d4-a716-446655440020, so its rating can no longer change: a bound quote is the permanent record of what was bound. userMessages: - >- Quote 550e8400-e29b-41d4-a716-446655440002 is bound to policy 550e8400-e29b-41d4-a716-446655440020, so its rating can no longer change: a bound quote is the permanent record of what was bound. referencingPolicy: 550e8400-e29b-41d4-a716-446655440020 quoteCancelled: summary: The quote is cancelled value: error: code: QuoteNotEditable message: >- Quote 550e8400-e29b-41d4-a716-446655440002 is cancelled, so its rating can no longer change: a cancelled quote is closed. userMessages: - >- Quote 550e8400-e29b-41d4-a716-446655440002 is cancelled, so its rating can no longer change: a cancelled quote is closed. '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier quoteIdPath: name: quoteId in: path required: true schema: type: string format: uuid description: Quote identifier schemas: ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' userMessages: type: array description: >- Clean, verbatim-displayable messages — one entry per failure, free of error-code tags, field paths, and internal noise. Suitable for showing to end users as-is. items: type: string example: - Exposures of type 'company' require an address details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId code: type: string description: Stable problem code for this individual validation failure example: BLANK_LIST_ELEMENT reason: type: string description: Stable reason the value violates its canonical contract example: blank-list-element expected: type: string description: The expected canonical value contract example: nonblank trimmed string message: type: string description: Description of the field error example: Required field is missing responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: AuthenticationError message: API key authentication required userMessages: - API key authentication required invalidApiKey: summary: >- Invalid API key (e.g. unknown key, or a Bearer token used instead of an API key) value: error: code: AuthenticationError message: Invalid API key userMessages: - Invalid API key Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: AuthorizationError message: User is not authorized to perform the requested action userMessages: - User is not authorized to perform the requested action companyMismatch: summary: A valid API key naming another company in the URL value: error: code: AuthorizationError message: API key is not scoped to the requested company userMessages: - API key is not scoped to the requested company InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: UncaughtActionError message: Uncaught error occurred in userMessages: - An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Send your raw API key as the `Authorization` header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key` header; those are not accepted. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- User-principal OAuth 2.0 Bearer authentication. Send a user-scoped Auth0 access token (audience = the app API audience) as `Authorization: Bearer `. The request resolves to the user's identity and is authorized by their Role on the `{companyId}` in the path — the same role-based permissions the web app enforces. This is the path the MCP connector uses to act on a user's behalf; endpoints that accept it list both `BearerAuth` and `ApiKeyAuth`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.