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

# Optimization candidates

> Returns factual optimization candidates - active monthly subscriptions with their current annualized cost, and subscriptions whose monthly cost exceeds twice the per-currency average. No discount rates are invented.



## OpenAPI

````yaml /api/openapi.yaml get /api/v1/analytics/optimizations
openapi: 3.1.0
info:
  title: Subscription Manager Public API
  version: 1.0.0
  description: >-
    Public API for subscription CRUD automation through Developer API keys. The
    operation descriptions include AI-oriented task semantics, risk levels, and
    confirmation guidance for agent integrations.
servers:
  - url: https://your-site.example
    description: Replace with your deployed Subscription Manager site URL.
security:
  - bearerApiKey: []
tags:
  - name: Subscriptions
    description: Create, read, update, and delete subscriptions for the API key owner.
    x-ai:
      domain: subscription_management
      ownerScope: authenticated_api_key_owner
      writeSafety: >-
        Confirm create, update, cancel, pause, resume, and delete operations
        with the user before calling them from an AI agent. Write operations
        require an API key with the write scope.
  - name: Analytics
    description: >-
      Computed spend summaries, duplicate detection, and optimization
      candidates. Read-only; money is reported per currency and never converted.
  - name: Audit
    description: Read-only audit trail of write operations performed through the API.
paths:
  /api/v1/analytics/optimizations:
    get:
      tags:
        - Analytics
      summary: Optimization candidates
      description: >-
        Returns factual optimization candidates - active monthly subscriptions
        with their current annualized cost, and subscriptions whose monthly cost
        exceeds twice the per-currency average. No discount rates are invented.
      operationId: getOptimizationSuggestions
      responses:
        '200':
          description: Optimization candidates returned.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptimizationsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    XRateLimitLimit:
      description: Total allowed requests in the current fixed window.
      schema:
        type: integer
        example: 60
    XRateLimitRemaining:
      description: Requests remaining in the current fixed window.
      schema:
        type: integer
        example: 59
    XRateLimitReset:
      description: Unix timestamp in seconds when the fixed window resets.
      schema:
        type: integer
        example: 1781690400
    RetryAfter:
      description: >-
        Seconds to wait before retrying. Sent with 429 responses, including when
        too many invalid API key attempts are throttled.
      schema:
        type: integer
        example: 2700
  schemas:
    OptimizationsResponse:
      type: object
      required:
        - optimizations
        - requestId
      properties:
        optimizations:
          type: object
          properties:
            monthlyToAnnual:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  currency:
                    type: string
                  monthlyAmount:
                    type: number
                  yearlyAtCurrentRate:
                    type: number
            aboveAverageInCurrency:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  currency:
                    type: string
                  monthlyEquivalent:
                    type: number
                  currencyMonthlyAverage:
                    type: number
        requestId:
          type: string
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
        - error
        - requestId
      properties:
        error:
          $ref: '#/components/schemas/Error'
        requestId:
          type: string
      additionalProperties: false
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        field:
          type: string
          description: Field that caused the error when the server can identify one.
        suggestedFix:
          type: string
          description: Human- and AI-readable correction hint.
        allowedValues:
          type: array
          items:
            type: string
          description: Allowed enum values when the error is caused by an unsupported enum.
        writableFields:
          type: array
          items:
            type: string
          description: >-
            Writable subscription fields when the error is caused by a
            non-writable field.
      additionalProperties: false
  responses:
    Unauthorized:
      description: The API key is missing, invalid, or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidApiKey:
              value:
                error:
                  code: invalid_api_key
                  message: Invalid API key
                requestId: request-1
    RateLimited:
      description: The user request limit or invalid-auth attempt limit was exceeded.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimited:
              value:
                error:
                  code: rate_limit_exceeded
                  message: Rate limit exceeded
                requestId: request-1
            tooManyInvalidKeys:
              value:
                error:
                  code: rate_limit_exceeded
                  message: Too many invalid API key attempts
                requestId: request-1
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal:
              value:
                error:
                  code: internal_error
                  message: Internal server error
                requestId: request-1
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      description: >-
        Developer API key generated in the app. Keys carry scopes; a read key
        can call list, get, analytics, and audit endpoints, while a write key
        additionally allows create, update, cancel, pause, resume, and delete.
      x-default: subm_your_key_here

````