{
  "openapi": "3.1.0",
  "info": {
    "title": "MindFrame Public API",
    "version": "2026-10-01",
    "description": "Public reads and authenticated five-game recording contracts. Public beta: aggregate counters stay unavailable until public launch. Per-run declarations are self-reported; competitive account classification is a separate contract. Proprietary — All Rights Reserved, VaultSpark Studios LLC.",
    "contact": {
      "email": "support@usemindframe.com",
      "url": "https://usemindframe.com/agents"
    }
  },
  "servers": [
    {
      "url": "https://api.usemindframe.com/api/v1"
    }
  ],
  "paths": {
    "/public/analytics/proof": {
      "get": {
        "summary": "Aggregate platform evidence",
        "description": "Totals and per-mode accuracy/calibration. Cached at the edge for five minutes.",
        "responses": {
          "200": {
            "description": "Aggregate evidence",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totalUsers": {
                      "type": "integer"
                    },
                    "totalSessions": {
                      "type": "integer",
                      "description": "All-time completed sessions, excluding internal test accounts."
                    },
                    "sessionsThisWeek": {
                      "type": "integer",
                      "description": "Completed sessions in the last 7 days (rolling), excluding internal test accounts."
                    },
                    "totalChallenges": {
                      "type": "integer",
                      "description": "Challenge answers submitted in completed sessions, excluding internal test accounts."
                    },
                    "avgCalibrationImprovement": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "byMode": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "mode": {
                            "type": "string"
                          },
                          "sessions": {
                            "type": "integer"
                          },
                          "avgAccuracy": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "avgCalibrationError": {
                            "type": [
                              "number",
                              "null"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/public/analytics/passport/{handle}": {
      "get": {
        "summary": "Public calibration passport",
        "description": "Only available when the user has opted into a public profile. Returns the 8-axis Cognitive Fingerprint. Keyed on the owner's public handle; legacy user ids still resolve.",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public passport (see /agents.json → agentInteractions for the field contract)"
          },
          "404": {
            "description": "No public profile"
          }
        }
      }
    },
    "/public/analytics/daily-activity": {
      "get": {
        "summary": "Today's aggregate activity",
        "responses": {
          "200": {
            "description": "Players today and aggregate calibration for today"
          }
        }
      }
    },
    "/games/outcomes": {
      "post": {
        "summary": "Record one finished game run (authenticated)",
        "description": "Six games only; ASCENT uses expedition manifests. Self-reported outcome, idempotent per idempotencyKey. Only explicitly declared human play can earn human XP. Agent and unattributed outcomes are excluded from human game summaries and personal bests. Memory Heist can open a delayed vault (delayedVaultDueAt) and record one return to it later (phase \"delayed\" + vaultSourceKey).",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "gameId",
                  "seed",
                  "contentVersion",
                  "outcome",
                  "assisted",
                  "durationMs",
                  "idempotencyKey"
                ],
                "properties": {
                  "gameId": {
                    "enum": [
                      "evidence-showdown",
                      "rule-shift",
                      "signal-station",
                      "memory-heist",
                      "fog-cartographer"
                    ]
                  },
                  "seed": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 2147483647
                  },
                  "contentVersion": {
                    "type": "string",
                    "maxLength": 40,
                    "pattern": "^[\\w.-]+$"
                  },
                  "outcome": {
                    "enum": [
                      "won",
                      "lost",
                      "abandoned"
                    ]
                  },
                  "assisted": {
                    "type": "boolean"
                  },
                  "durationMs": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 21600000,
                    "description": "Elapsed wall time including reloads. Use0 when unknown; unknown times cannot set personal bests."
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{8,64}$"
                  },
                  "actor": {
                    "type": "object",
                    "description": "Self-declared until Obelisk agent identity is live.",
                    "properties": {
                      "kind": {
                        "enum": [
                          "human",
                          "agent"
                        ]
                      },
                      "agentId": {
                        "type": "string",
                        "maxLength": 128
                      }
                    }
                  },
                  "phase": {
                    "enum": [
                      "immediate",
                      "delayed"
                    ],
                    "default": "immediate",
                    "description": "Optional. \"delayed\" records a Memory Heist vault return; delayed runs never set personal bests and are summarised separately."
                  },
                  "delayedVaultDueAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Optional, Memory Heist immediate runs only: open a delayed vault due at this time, 4 hours to 7 days ahead."
                  },
                  "vaultSourceKey": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{8,64}$",
                    "description": "Required when phase is \"delayed\": the idempotencyKey of the immediate run that opened the vault. One return per vault; not before its dueAt."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recorded (or recognised as a duplicate)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "duplicate": {
                      "type": "boolean"
                    },
                    "xpAwarded": {
                      "type": "integer"
                    },
                    "dailyXpRemaining": {
                      "type": "integer"
                    },
                    "xpNote": {
                      "enum": [
                        "agent-play",
                        "unattributed-play",
                        "assisted",
                        "daily-cap",
                        "abandoned",
                        null
                      ]
                    },
                    "personalBest": {
                      "type": "object",
                      "description": "Set for an unassisted human immediate win.",
                      "properties": {
                        "previousBestMs": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "isNewBest": {
                          "type": "boolean"
                        }
                      }
                    },
                    "phase": {
                      "enum": [
                        "immediate",
                        "delayed"
                      ]
                    },
                    "delayedVault": {
                      "type": "object",
                      "description": "Set when an immediate run opened a delayed vault.",
                      "properties": {
                        "dueAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid game, payload or bounded field, or an invalid delayed-vault request"
          },
          "401": {
            "description": "Not signed in"
          },
          "409": {
            "description": "This vault was already returned to"
          },
          "429": {
            "description": "Rate limited (30 per minute)"
          }
        }
      }
    },
    "/ascent/expedition/start": {
      "post": {
        "summary": "Issue an owned expedition manifest",
        "description": "10/min. Issued proof is empty; expiresAt is the submission deadline. An omitted body preserves expedition-v3 for existing clients. Specify expedition-v4 for the cinematic climb; difficulty and focus are explicit authored-trail preferences.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Manifest issued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ownerSubject",
                    "manifestId",
                    "proof",
                    "expiresAt"
                  ],
                  "properties": {
                    "ownerSubject": {
                      "type": "string"
                    },
                    "manifestId": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "proof": {
                      "$ref": "#/components/schemas/ExpeditionProof"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or unsupported expedition preferences"
          },
          "401": {
            "description": "Not signed in"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "ruleset": {
                    "type": "string",
                    "enum": [
                      "expedition-v4"
                    ]
                  },
                  "difficulty": {
                    "type": "string",
                    "enum": [
                      "apprentice",
                      "standard",
                      "expert"
                    ]
                  },
                  "focus": {
                    "type": "string",
                    "enum": [
                      "balanced",
                      "evidence",
                      "planning",
                      "assumptions"
                    ]
                  }
                },
                "description": "Preferences require ruleset expedition-v4. Null and unknown values are rejected."
              }
            }
          }
        }
      }
    },
    "/ascent/expedition/submit": {
      "post": {
        "summary": "Replay and save a completed expedition",
        "description": "20/min. Retries retain the same manifest, proof and actor. No human XP is awarded.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "manifestId",
                  "proof"
                ],
                "properties": {
                  "manifestId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64
                  },
                  "proof": {
                    "$ref": "#/components/schemas/ExpeditionProof"
                  },
                  "actor": {
                    "$ref": "#/components/schemas/RunActor"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Saved or identical retry accepted; includes ownerSubject, manifestId, altitude, stages, outcome, proofDigest and actor"
          },
          "400": {
            "description": "Invalid, nonterminal, mismatched or expired proof"
          },
          "401": {
            "description": "Not signed in"
          },
          "404": {
            "description": "Owned manifest not found"
          },
          "409": {
            "description": "Conflicting submission"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/ascent/expedition/history": {
      "get": {
        "summary": "Read owned expedition results and separate actor populations",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "ownerSubject, labelled rows, separate populations; combined aggregates are unavailable"
          },
          "401": {
            "description": "Not signed in"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/games/outcomes/summary": {
      "get": {
        "summary": "Explicit-human progress for the four outcome games",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Per-game plays, wins, lastPlayedAt and bestWinMs (null if unknown), plus delayed vault returns reported separately and pending delayed vaults",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "games": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "gameId": {
                            "type": "string"
                          },
                          "plays": {
                            "type": "integer"
                          },
                          "wins": {
                            "type": "integer"
                          },
                          "lastPlayedAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "bestWinMs": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "delayed": {
                            "type": "object",
                            "description": "Delayed vault returns; never merged into immediate plays, wins or bestWinMs.",
                            "properties": {
                              "plays": {
                                "type": "integer"
                              },
                              "wins": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    },
                    "delayedVaults": {
                      "type": "array",
                      "description": "Delayed vaults opened but not yet returned to.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "gameId": {
                            "type": "string"
                          },
                          "sourceIdempotencyKey": {
                            "type": "string"
                          },
                          "seed": {
                            "type": "integer"
                          },
                          "contentVersion": {
                            "type": "string"
                          },
                          "dueAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "due": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not signed in"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "RunActor": {
        "type": "object",
        "description": "Self-declared until Obelisk agent identity is live.",
        "properties": {
          "kind": {
            "enum": [
              "human",
              "agent"
            ]
          },
          "agentId": {
            "type": "string",
            "maxLength": 128
          }
        }
      },
      "ExpeditionProof": {
        "type": "object",
        "description": "Versioned seed, ruleset, contentVersion and ordered actions. Begin with the server-issued proof; preserve its versions and append legal game actions until summit/rescued.",
        "required": [
          "seed",
          "ruleset",
          "contentVersion",
          "actions"
        ],
        "properties": {
          "seed": {
            "type": "integer"
          },
          "ruleset": {
            "type": "string"
          },
          "contentVersion": {
            "type": "string"
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  }
}
