Marz Greta-Lock Network Operator API

openapi: 3.2.0
info:
  title: EQ Scoring Platform — Human-Likeness & AI Text Benchmark…
  description: 'Human-likeness scoring and AI text benchmark API. Score AI-generated text against real human personality profiles (EQ, formality, directness, hesitation, response-timing cadence) to measure how human your AI writing sounds before you ship it. Built for autonomous agents and AI text humanizer pipelines: free stateless scoring at /api/score, paid validated benchmarks via machine-to-machine On-chain settlement with x402 support — the default path is gasless USDC on Base (unpaid calls to /api/simulate return HTTP 402 with machine-readable payment requirements; sign the Base requirement and retry once with PAYMENT-SIGNATURE). Legacy SOL and X-PAYMENT clients remain compatible. Interactive API docs are available at /api/docs. Permanent tool setup (wire it in once and explicitly authorize a dedicated USDC-on-Base burner wallet so the SDK can sign paid calls without a human): see the ''Permanent tool setup'' section of /llms.txt and the crawlable guide at /guides/permanent-agent-tool-setup.html. Live network stats (real ledger aggregates) at /api/stats; runnable Python/JS quickstart examples ship in the repo under examples/.'
  version: 1.0.0
tags:
- name: Operator
paths:
  /api/operator/corpus-insights:
    get:
      summary: Corpus Insights
      description: 'Operator-only learning report from the consented free-trial corpus.


        Per profile: how many clean samples exist, average score, and the

        measured uplift when bots say they applied our previous suggestion —

        the evidence base for evolving better tests and coaching.'
      operationId: corpus_insights_api_operator_corpus_insights_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/public-results/conversion:
    get:
      summary: Public Result Conversion Report
      description: Aggregate, identity-free public-result funnel for operators.
      operationId: public_result_conversion_report_api_operator_public_results_conversion_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicResultConversionResponse'
      tags:
      - Operator
  /api/operator/aei-pilot-evidence:
    get:
      summary: Operator Evidence
      operationId: operator_evidence_api_operator_aei_pilot_evidence_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/aei/reinafin:
    get:
      summary: Reinafin Access Usage
      operationId: reinafin_access_usage_api_operator_aei_reinafin_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
    post:
      summary: Manage Reinafin Access
      operationId: manage_reinafin_access_api_operator_aei_reinafin_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AEISponsoredAction'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Operator
  /api/operator/aei-evidence:
    get:
      summary: Operator Aei Evidence
      operationId: operator_aei_evidence_api_operator_aei_evidence_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/learning-evidence:
    get:
      summary: Operator Learning Evidence
      operationId: operator_learning_evidence_api_operator_learning_evidence_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/guidance-review/volunteers:
    get:
      summary: Operator Guidance Review Volunteers
      operationId: operator_guidance_review_volunteers_api_operator_guidance_review_volunteers_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/support/inquiries:
    get:
      summary: Operator Support Inquiries
      operationId: operator_support_inquiries_api_operator_support_inquiries_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/support/inquiries/latest:
    get:
      summary: Operator Support Inquiry Latest
      description: Lightweight alert cursor; never returns inquiry contact data.
      operationId: operator_support_inquiry_latest_api_operator_support_inquiries_latest_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/free-trial/whoami:
    get:
      summary: Free Trial Whoami
      description: 'Operator-only diagnostic: echo the X-Forwarded-For chain, per-hop skip

        classification, and the caller key the free-trial cap would use for this

        request. Exists to verify caller-key derivation against the REAL proxy

        chain in each environment (the published LB tail differs from dev).'
      operationId: free_trial_whoami_api_operator_free_trial_whoami_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/free-trial/contacts:
    get:
      summary: Free Trial Contacts
      description: 'Operator-only: list free-trial callers who left an optional contact

        (email or callback URL) with a free score, newest first — the outreach

        list for follow-up offers. Also includes a 12-week contact cohort matching

        the Funnel page''s new-free-caller window.'
      operationId: free_trial_contacts_api_operator_free_trial_contacts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/free-trial/purge-stale:
    post:
      summary: Purge Stale Free Trial Rows
      description: 'Clean up free_score_usage rows keyed by rotating LB IPs (stale buckets

        created before the caller-key fix). Requires operator authorization.


        Without `keys`, returns candidate stale rows (dry run). With `keys`,

        deletes exactly those rows — the operator confirms the specific keys, so a

        legitimate client that happens to live in a Google range is never purged

        without review.'
      operationId: purge_stale_free_trial_rows_api_operator_free_trial_purge_stale_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FreeTrialPurgeInput'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Operator
  /api/operator/free-trial/reset-caller:
    post:
      summary: Reset Free Trial Caller
      description: 'Operator-only: zero out the free-trial usage count for one specific

        caller key so the full cap-exhaustion sequence can be re-verified without

        repurposing the stale-purge endpoint.


        The row is deleted (not updated to 0) so the caller starts completely

        fresh — same state as a brand-new caller who has never scored.

        Wishlist rows for this caller are NOT removed; those are independent.'
      operationId: reset_free_trial_caller_api_operator_free_trial_reset_caller_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FreeTrialResetCallerInput'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Operator
  /api/operator/session:
    get:
      summary: Operator Session
      description: Report whether the caller holds a valid operator session.
      operationId: operator_session_api_operator_session_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/logout:
    post:
      summary: Operator Logout
      description: Clear the operator session cookie.
      operationId: operator_logout_api_operator_logout_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Operator
  /api/operator/login:
    post:
      summary: Operator Login
      description: Exchange the operator key for a server-managed HttpOnly session cookie.
      operationId: operator_login_api_operator_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperatorLoginInput'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Operator
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PublicResultProfileConversionResponse:
      properties:
        profile:
          type: string
          title: Profile
        result_views:
          type: integer
          title: Result Views
        new_scores:
          type: integer
          title: New Scores
        second_sessions:
          type: integer
          title: Second Sessions
        verified_paid_within_7_days:
          type: integer
          title: Verified Paid Within 7 Days
        viewer_to_score_conversion_pct:
          type: number
          title: Viewer To Score Conversion Pct
        viewer_to_verified_paid_7_day_conversion_pct:
          type: number
          title: Viewer To Verified Paid 7 Day Conversion Pct
        suppressed:
          type: boolean
          title: Suppressed
      type: object
      required:
      - profile
      - result_views
      - new_scores
      - second_sessions
      - verified_paid_within_7_days
      - viewer_to_score_conversion_pct
      - viewer_to_verified_paid_7_day_conversion_pct
      - suppressed
      title: PublicResultProfileConversionResponse
    PublicResultConversionResponse:
      properties:
        viewers:
          type: integer
          title: Viewers
        viewers_to_score:
          type: integer
          title: Viewers To Score
        attributed_scores:
          type: integer
          title: Attributed Scores
        second_session_viewers:
          type: integer
          title: Second Session Viewers
        verified_paid_within_7_days:
          type: integer
          title: Verified Paid Within 7 Days
        viewer_to_score_conversion_pct:
          type: number
          title: Viewer To Score Conversion Pct
        viewer_to_verified_paid_7_day_conversion_pct:
          type: number
          title: Viewer To Verified Paid 7 Day Conversion Pct
        profile_breakdown:
          items:
            $ref: '#/components/schemas/PublicResultProfileConversionResponse'
          type: array
          title: Profile Breakdown
        cohort_suppression_threshold:
          type: integer
          title: Cohort Suppression Threshold
        privacy:
          type: string
          title: Privacy
      type: object
      required:
      - viewers
      - viewers_to_score
      - attributed_scores
      - second_session_viewers
      - verified_paid_within_7_days
      - viewer_to_score_conversion_pct
      - viewer_to_verified_paid_7_day_conversion_pct
      - profile_breakdown
      - cohort_suppression_threshold
      - privacy
      title: PublicResultConversionResponse
    OperatorLoginInput:
      properties:
        key:
          type: string
          title: Key
      type: object
      required:
      - key
      title: OperatorLoginInput
    FreeTrialResetCallerInput:
      properties:
        caller_key:
          type: string
          title: Caller Key
      type: object
      required:
      - caller_key
      title: FreeTrialResetCallerInput
    FreeTrialPurgeInput:
      properties:
        keys:
          items:
            type: string
          type: array
          title: Keys
          default: []
      type: object
      title: FreeTrialPurgeInput
    AEISponsoredAction:
      properties:
        action:
          type: string
          enum:
          - provision
          - rotate
          - revoke
          title: Action
      additionalProperties: false
      type: object
      required:
      - action
      title: AEISponsoredAction
x-provenance:
  method: harvested
  publisher: Marz Greta-Lock Network
  source: https://eqbuilder.dev/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)