openapi: 3.2.0
info:
  contact:
    email: support@aiapplyd.com
    name: AI Applyd
    url: https://aiapplyd.com
  description: 'The AI Applyd API runs the whole job hunt for you: it matches you to roles that fit your profile, rewrites your resume for each posting, writes the cover letter the form asks for, and auto-applies across the major applicant tracking systems.'
  license:
    name: Proprietary
    url: https://aiapplyd.com/legal/terms
  title: AI Applyd Proof Points API
  version: 115c47ce
servers:
- description: Current environment
  url: https://api.aiapplyd.com/api/v1
security:
- BearerAuth: []
tags:
- name: proof-points
paths:
  /proof-points:
    get:
      tags:
      - proof-points
      summary: List Proof Points
      description: List the authenticated user's proof points (evidence bank), optionally filtered by category.
      parameters:
      - schema:
          type: string
          enum:
          - revenue
          - headcount
          - efficiency
          - delivery
          - technical
          - leadership
          description: Filter to a single category
          example: delivery
        required: false
        description: Filter to a single category
        name: category
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          description: Maximum proof points to return
          example: 50
        required: false
        description: Maximum proof points to return
        name: limit
        in: query
      - schema:
          type: string
          description: Deprecated, ignored. Kept for backwards compatibility with cached frontend bundles.
        required: false
        description: Deprecated, ignored. Kept for backwards compatibility with cached frontend bundles.
        name: includeArchived
        in: query
      responses:
        '200':
          description: Proof points retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofPointListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: getProofPoints
    post:
      tags:
      - proof-points
      summary: Create Proof Point
      description: Create a new proof point in the user's evidence bank. Capped at 50 per user.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProofPoint'
      responses:
        '201':
          description: Proof point created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofPointResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: postProofPoints
  /proof-points/suggest:
    post:
      tags:
      - proof-points
      summary: Suggest Proof Points
      description: Generate proof points from the user's most recent resume and insert them into the bank. Returns the created rows. Skipped with `reason` when no resume exists, the per-user ceiling is reached, or the AI returned nothing usable.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestProofPointsRequest'
      responses:
        '200':
          description: Proof points created (or skipped with reason)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofPointSuggestionsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: postProofPointsSuggest
  /proof-points/{id}:
    patch:
      tags:
      - proof-points
      summary: Update Proof Point
      description: Update an existing proof point by id.
      parameters:
      - schema:
          type: string
          pattern: ^\d+$
          description: Proof point identifier (auto-increment integer)
          example: '1'
        required: true
        description: Proof point identifier (auto-increment integer)
        in: path
        name: id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProofPoint'
      responses:
        '200':
          description: Proof point updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofPointResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: patchProofPointsById
    delete:
      tags:
      - proof-points
      summary: Delete Proof Point
      description: Hard-delete a proof point. No soft-archive / no rollback window.
      parameters:
      - schema:
          type: string
          pattern: ^\d+$
          description: Proof point identifier (auto-increment integer)
          example: '1'
        required: true
        description: Proof point identifier (auto-increment integer)
        in: path
        name: id
      responses:
        '200':
          description: Proof point deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofPointDeletedResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      operationId: deleteProofPointsById
components:
  schemas:
    ProofPointData:
      type: object
      properties:
        architectureSummary:
          type:
          - string
          - 'null'
          description: High-level architecture / approach summary
          example: Migrated 12 monolith services to a Hono + D1 multi-tenant Workers stack...
        category:
          type: string
          enum:
          - revenue
          - headcount
          - efficiency
          - delivery
          - technical
          - leadership
          description: Category tag for a proof point in the user's evidence bank
          example: delivery
        createdAt:
          type: string
          description: Creation timestamp (ISO-8601)
          example: '2026-01-15T12:00:00Z'
        heroMetric:
          type:
          - string
          - 'null'
          description: One-line hero metric the cover letter / match report will lead with
          example: $2M ARR / 10x latency reduction
        id:
          type: integer
          description: Proof point identifier
          example: 12
        keyDecisions:
          type: array
          items:
            type: string
          description: Tradeoffs / non-obvious decisions the candidate made
          example:
          - Picked SQLite over Postgres because read amplification was the bottleneck
          - Wrote the migrator as a one-shot script instead of a service
        sortOrder:
          type: integer
          description: Manual sort order; smaller = higher in list
          example: 0
        sourceResumeDocId:
          type:
          - integer
          - 'null'
          description: Source resume document this proof point was extracted from
          example: 42
        title:
          type: string
          description: Short memorable label for the project
          example: Project Phoenix migration
        updatedAt:
          type: string
          description: Last update timestamp (ISO-8601)
          example: '2026-03-10T08:30:00Z'
        userId:
          type: string
          description: Owner user identifier
          example: user_123
      required:
      - architectureSummary
      - category
      - createdAt
      - heroMetric
      - id
      - keyDecisions
      - sortOrder
      - sourceResumeDocId
      - title
      - updatedAt
      - userId
      additionalProperties: false
    ProofPointSuggestionsData:
      type: object
      properties:
        created:
          type: array
          items:
            $ref: '#/components/schemas/ProofPointData'
          description: Newly inserted proof points (already persisted to the user bank).
        reason:
          type:
          - string
          - 'null'
          enum:
          - no_resume_on_file
          - cap_reached
          - ai_returned_no_items
          - null
          description: Set when no proof points were created. null on success.
          example: no_resume_on_file
        tokensSpent:
          type: integer
          description: Tokens deducted from the user balance for this request. 0 when skipped.
          example: 5
      required:
      - created
      - reason
      - tokensSpent
      additionalProperties: false
    ProofPointSuggestionsResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ProofPointSuggestionsData'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    ProofPointListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/ProofPointData'
          required:
          - items
          additionalProperties: false
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    ResponseMetadata:
      type: object
      properties:
        duration:
          type: number
          description: Request duration in milliseconds
          example: 150
          exclusiveMinimum: 0
        performance:
          type: object
          properties:
            dbQueries:
              type: integer
              minimum: 0
            totalDbTime:
              type: number
              minimum: 0
          description: Performance metrics (preview/local only)
        requestId:
          type: string
          description: Unique request identifier
          example: req_abc123
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp
          example: '2026-09-25T17:29:47.224Z'
        version:
          type: string
          description: API version
          example: v1
    ProofPointResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ProofPointData'
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    UpdateProofPoint:
      type: object
      properties:
        architectureSummary:
          type:
          - string
          - 'null'
          maxLength: 4000
          description: High-level architecture / approach summary
        category:
          type: string
          enum:
          - revenue
          - headcount
          - efficiency
          - delivery
          - technical
          - leadership
          description: Category tag for a proof point in the user's evidence bank
          example: delivery
        heroMetric:
          type:
          - string
          - 'null'
          maxLength: 200
          description: One-line hero metric
          example: $2M ARR / 10x latency reduction
        keyDecisions:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 500
          maxItems: 10
          description: Tradeoffs / non-obvious decisions
        sortOrder:
          type: integer
          minimum: 0
          maximum: 1000
          description: Manual sort order (smaller = higher)
        sourceResumeDocId:
          type:
          - integer
          - 'null'
          description: Source resume document this proof point came from
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Short memorable label
          example: Project Phoenix migration
      additionalProperties: false
    CreateProofPoint:
      type: object
      properties:
        architectureSummary:
          type:
          - string
          - 'null'
          maxLength: 4000
          description: High-level architecture / approach summary
        category:
          type: string
          enum:
          - revenue
          - headcount
          - efficiency
          - delivery
          - technical
          - leadership
          description: Category tag for a proof point in the user's evidence bank
          example: delivery
        heroMetric:
          type:
          - string
          - 'null'
          maxLength: 200
          description: One-line hero metric
          example: $2M ARR / 10x latency reduction
        keyDecisions:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 500
          maxItems: 10
          description: Tradeoffs / non-obvious decisions
        sortOrder:
          type: integer
          minimum: 0
          maximum: 1000
          description: Manual sort order (smaller = higher)
        sourceResumeDocId:
          type:
          - integer
          - 'null'
          description: Source resume document this proof point came from
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Short memorable label
          example: Project Phoenix migration
      required:
      - category
      - title
      additionalProperties: false
    SuggestProofPointsRequest:
      type: object
      properties: {}
      additionalProperties: false
    ProofPointDeletedResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            success:
              type: boolean
              enum:
              - true
          required:
          - success
          additionalProperties: false
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - true
      required:
      - data
      - success
      additionalProperties: false
      description: Successful API response
    ApiErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            context:
              oneOf:
              - type: object
                properties:
                  errorType:
                    type: string
                    enum:
                    - validation
                  field:
                    type: string
                  fieldErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        field:
                          type: string
                        message:
                          type: string
                        received:
                          type: string
                      required:
                      - field
                      - message
                  schemaName:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  attemptedEmail:
                    type: string
                    format: email
                  errorType:
                    type: string
                    enum:
                    - authentication
                  failureReason:
                    type: string
                    enum:
                    - invalid_credentials
                    - account_locked
                    - expired_token
                    - token_expired
                    - missing_token
                    - invalid_token
                    - session_expired
                    description: Reason for authentication failure
                    example: token_expired
                  ipAddress:
                    type: string
                  operation:
                    type: string
                  service:
                    type: string
                  userAgent:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  actualPermission:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - authorization
                  requiredPermission:
                    type: string
                  resource:
                    type: string
                  resourceId:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  constraint:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - database
                  operation:
                    type: string
                    enum:
                    - insert
                    - update
                    - delete
                    - select
                    - batch
                    - transaction
                    - migration
                    description: Type of database operation
                    example: select
                  resourceId:
                    type: string
                  sqlState:
                    type: string
                  table:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  endpoint:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - external_service
                  httpStatus:
                    type: number
                  operation:
                    type: string
                  resourceId:
                    type: string
                  responseTime:
                    type: number
                  retryAttempt:
                    type: integer
                  service:
                    type: string
                  serviceName:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  errorType:
                    type: string
                    enum:
                    - resource
                  resource:
                    type: string
                  resourceId:
                    type: string
                  service:
                    type: string
                  userId:
                    type: string
                required:
                - errorType
              - type: object
                properties:
                  errorType:
                    type: string
                    enum:
                    - rate_limit
                  limit:
                    type: number
                  resetTime:
                    type: string
                  windowMs:
                    type: number
                required:
                - errorType
              - type: object
                properties:
                  configKey:
                    type: string
                  errorType:
                    type: string
                    enum:
                    - configuration
                  operation:
                    type: string
                  service:
                    type: string
                required:
                - errorType
              description: Type-safe error context information
              example:
                errorType: validation
                fieldErrors:
                - field: email
                  message: Invalid email format
            details:
              oneOf:
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - validation
                  validationErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        field:
                          type: string
                        message:
                          type: string
                      required:
                      - field
                      - message
                required:
                - detailType
                - validationErrors
                additionalProperties: false
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - service_error
                  originalError:
                    type: string
                  serviceName:
                    type: string
                required:
                - detailType
                - serviceName
                additionalProperties: false
              - type: object
                properties:
                  currentSize:
                    type: number
                  detailType:
                    type: string
                    enum:
                    - batch
                  originalError:
                    type: string
                  statementCount:
                    type: number
                required:
                - detailType
                additionalProperties: false
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - rate_limit
                  limit:
                    type: number
                  resetTime:
                    type: string
                  windowMs:
                    type: number
                required:
                - detailType
                - limit
                - resetTime
                - windowMs
                additionalProperties: false
              - type: object
                properties:
                  conflictingField:
                    type: string
                  detailType:
                    type: string
                    enum:
                    - resource
                  resourceId:
                    anyOf:
                    - type: string
                    - type: number
                  resourceType:
                    type: string
                required:
                - detailType
                additionalProperties: false
              - type: object
                properties:
                  detailType:
                    type: string
                    enum:
                    - generic
                  info:
                    type: string
                required:
                - detailType
                additionalProperties: false
              - type: object
                properties:
                  currentTokens:
                    type: integer
                    minimum: 0
                  detailType:
                    type: string
                    enum:
                    - insufficient_tokens
                  requiredTokens:
                    type: integer
                    minimum: 0
                required:
                - currentTokens
                - detailType
                - requiredTokens
                additionalProperties: false
            message:
              type: string
            validation:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                - field
                - message
                additionalProperties: false
          required:
          - code
          - message
          additionalProperties: false
        meta:
          $ref: '#/components/schemas/ResponseMetadata'
        success:
          type: boolean
          enum:
          - false
      required:
      - error
      - success
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      description: 'Session token from signing in to AI Applyd, sent as `Authorization: Bearer <token>`.'
      scheme: bearer
      type: http