{
  "openapi": "3.1.0",
  "info": {
    "title": "Sapere Intelligence API",
    "version": "1.1.0",
    "description": "The desk's graded record, calls and market intelligence as read-only endpoints. Every call is timestamped before its outcome. Observer access uses a 24-hour delay. Research, not financial advice.",
    "contact": {
      "url": "https://app.sapere.one/api"
    }
  },
  "servers": [
    {
      "url": "https://app.sapere.one/v1"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/api/public/desk": {
      "get": {
        "operationId": "getPublicDeskSnapshot",
        "summary": "The public Sapere Desk snapshot",
        "description": "A fixed, unauthenticated projection for the Sapere Desk Agent. Calls and research use a 24-hour public delay.",
        "servers": [
          {
            "url": "https://app.sapere.one"
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "A live, source-linked public snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicDeskSnapshot"
                }
              }
            }
          },
          "400": {
            "description": "Query parameters are not supported."
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/record": {
      "get": {
        "operationId": "getRecord",
        "summary": "The graded track record",
        "description": "The full audit trail and the clean era (entry-integrity + net-of-costs), each with Wilson 95% intervals on rates and a percentile-bootstrap interval on expectancy.",
        "responses": {
          "200": {
            "description": "The record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "full": {
                      "$ref": "#/components/schemas/RecordBlock"
                    },
                    "clean": {
                      "$ref": "#/components/schemas/RecordBlock"
                    },
                    "clean_era_start": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "methodology": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/calls": {
      "get": {
        "operationId": "listCalls",
        "summary": "Graded and open calls, newest first",
        "description": "Major calls in the public projection. Observer-tier keys receive nothing newer than 24 hours.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Which calls to return. closed (default; observer keys see these 24h delayed), open (live calls), or all. Observer tier is closed-only.",
            "schema": {
              "type": "string",
              "enum": [
                "closed",
                "open",
                "all"
              ],
              "default": "closed"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of calls.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "calls": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MajorCall"
                      }
                    },
                    "count": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/radar": {
      "get": {
        "operationId": "listRadar",
        "summary": "Emergence radar — the WATCH list",
        "description": "New-listing WATCH candidates, verified and scored, highest score first. Display-only: every row is sized:false and outside the majors universe. Analyst tier and above only (observer keys receive 403); analyst gets the headline, desk and up also receive the audit trail.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of WATCH candidates.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "radar": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WatchCard"
                      }
                    },
                    "count": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Radar is available on the analyst tier and above."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/calls/{id}": {
      "get": {
        "operationId": "getCall",
        "summary": "One call by id",
        "description": "A single major or prediction call, resolved by the same rules as the public permalink at app.sapere.one/call/{id}.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The call.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/MajorCall"
                    },
                    {
                      "$ref": "#/components/schemas/PredictionCall"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No call with that id."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/intelligence/{symbol}": {
      "get": {
        "operationId": "getIntelligence",
        "summary": "The latest signal card for one covered major",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "BTC"
          }
        ],
        "responses": {
          "200": {
            "description": "The current quantitative read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Intelligence"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Symbol not covered."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid X-API-Key."
      },
      "RateLimited": {
        "description": "Per-key rate limit exceeded."
      },
      "Unavailable": {
        "description": "Upstream data temporarily unavailable."
      }
    },
    "schemas": {
      "PublicDeskSnapshot": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contract_version",
          "generated_at",
          "live",
          "delay_seconds",
          "freshness",
          "calls",
          "research",
          "links"
        ],
        "properties": {
          "contract_version": {
            "type": "integer",
            "const": 1
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "live": {
            "type": "boolean",
            "const": true
          },
          "delay_seconds": {
            "type": "integer",
            "const": 86400
          },
          "freshness": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "source_updated_at",
              "expires_at"
            ],
            "properties": {
              "source_updated_at": {
                "type": "string",
                "format": "date-time"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "calls": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "active",
              "resolved"
            ],
            "properties": {
              "active": {
                "type": "array",
                "maxItems": 10,
                "items": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PublicDeskMajorCall"
                    },
                    {
                      "$ref": "#/components/schemas/PublicDeskPredictionCall"
                    }
                  ]
                }
              },
              "resolved": {
                "type": "array",
                "maxItems": 10,
                "items": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PublicDeskMajorCall"
                    },
                    {
                      "$ref": "#/components/schemas/PublicDeskPredictionCall"
                    }
                  ]
                }
              }
            }
          },
          "research": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "$ref": "#/components/schemas/PublicDeskResearch"
            }
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "methodology",
              "research",
              "api",
              "agent"
            ],
            "properties": {
              "methodology": { "type": "string", "format": "uri" },
              "research": { "type": "string", "format": "uri" },
              "api": { "type": "string", "format": "uri" },
              "agent": { "type": "string", "format": "uri" }
            }
          }
        }
      },
      "PublicDeskMajorCall": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "kind",
          "phase",
          "id",
          "symbol",
          "direction",
          "leverage",
          "entry",
          "stop",
          "target",
          "result",
          "pnl_pct",
          "opened_at",
          "settled_at",
          "regime_at_open",
          "composite_at_open",
          "source_url"
        ],
        "properties": {
          "kind": { "type": "string", "const": "major" },
          "phase": { "type": "string", "enum": ["active", "resolved"] },
          "id": { "type": "string", "format": "uuid" },
          "symbol": { "type": "string" },
          "direction": { "type": "string", "enum": ["LONG", "SHORT"] },
          "leverage": { "type": "number" },
          "entry": { "type": "number" },
          "stop": { "type": ["number", "null"] },
          "target": { "type": ["number", "null"] },
          "result": { "type": "string", "enum": ["open", "win", "loss"] },
          "pnl_pct": { "type": ["number", "null"] },
          "opened_at": { "type": "string", "format": "date-time" },
          "settled_at": { "type": ["string", "null"], "format": "date-time" },
          "regime_at_open": { "type": ["string", "null"] },
          "composite_at_open": { "type": ["number", "null"] },
          "source_url": { "type": "string", "format": "uri" }
        }
      },
      "PublicDeskPredictionCall": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "kind",
          "phase",
          "id",
          "question",
          "side",
          "confidence",
          "market_implied_at_call",
          "revised",
          "result",
          "published_at",
          "settled_at",
          "source_url"
        ],
        "properties": {
          "kind": { "type": "string", "const": "prediction" },
          "phase": { "type": "string", "enum": ["active", "resolved"] },
          "id": { "type": "string", "format": "uuid" },
          "question": { "type": "string" },
          "side": { "type": "string", "enum": ["YES", "NO"] },
          "confidence": { "type": "integer", "minimum": 0, "maximum": 100 },
          "market_implied_at_call": { "type": "number", "minimum": 0, "maximum": 1 },
          "revised": { "type": "boolean" },
          "result": { "type": "string", "enum": ["open", "correct", "incorrect"] },
          "published_at": { "type": "string", "format": "date-time" },
          "settled_at": { "type": ["string", "null"], "format": "date-time" },
          "source_url": { "type": "string", "format": "uri" }
        }
      },
      "PublicDeskResearch": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "slug",
          "kind",
          "title",
          "published_at",
          "source_url"
        ],
        "properties": {
          "slug": { "type": "string" },
          "kind": { "type": "string", "enum": ["daily", "deep"] },
          "title": { "type": "string" },
          "published_at": { "type": "string", "format": "date-time" },
          "source_url": { "type": "string", "format": "uri" }
        }
      },
      "WatchCard": {
        "type": "object",
        "description": "An emergence-radar WATCH candidate. Display-only intelligence — never sized, never a major. Analyst keys receive the headline fields; desk and up also receive audit_flags, coingecko_id and components.",
        "properties": {
          "symbol": {
            "type": "string"
          },
          "score": {
            "type": "number",
            "description": "0–1 emergence score"
          },
          "band": {
            "type": "string",
            "enum": [
              "watch",
              "probe",
              "promotion"
            ]
          },
          "catalyst_tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "why it surfaced: listing venue, event type, perp build, ranked"
          },
          "sized": {
            "type": "boolean",
            "description": "always false"
          },
          "in_universe": {
            "type": "boolean",
            "description": "always false"
          },
          "audit_flags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "desk+ only: verification caveats (e.g. volume_unverified)"
          },
          "coingecko_id": {
            "type": "string",
            "description": "desk+ only: the canonical id"
          },
          "components": {
            "type": "object",
            "description": "desk+ only: the score component breakdown"
          },
          "published_at": {
            "type": "string"
          }
        }
      },
      "RecordBlock": {
        "type": "object",
        "description": "One era's honest summary of settled calls.",
        "properties": {
          "n": {
            "type": "integer"
          },
          "wins": {
            "type": "integer"
          },
          "losses": {
            "type": "integer"
          },
          "win_rate": {
            "type": [
              "number",
              "null"
            ]
          },
          "win_rate_ci": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Wilson 95% interval [lo, hi]"
          },
          "expectancy_pct": {
            "type": [
              "number",
              "null"
            ]
          },
          "expectancy_ci": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ]
            },
            "description": "bootstrap interval [lo, hi]"
          },
          "avg_win_pct": {
            "type": [
              "number",
              "null"
            ]
          },
          "avg_loss_pct": {
            "type": [
              "number",
              "null"
            ]
          },
          "profit_factor": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "MajorCall": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "const": "major"
          },
          "symbol": {
            "type": "string"
          },
          "direction": {
            "type": "string",
            "enum": [
              "long",
              "short"
            ]
          },
          "leverage": {
            "type": "number"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "closed"
            ]
          },
          "entry": {
            "type": "number"
          },
          "stop": {
            "type": [
              "number",
              "null"
            ]
          },
          "target": {
            "type": [
              "number",
              "null"
            ]
          },
          "pnl_pct": {
            "type": [
              "number",
              "null"
            ],
            "description": "net of modeled costs; null while open"
          },
          "close_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "opened_at": {
            "type": "string",
            "format": "date-time"
          },
          "closed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "regime_tag": {
            "type": [
              "string",
              "null"
            ]
          },
          "composite_score": {
            "type": [
              "number",
              "null"
            ]
          },
          "pnl_pct_gross": {
            "type": [
              "number",
              "null"
            ]
          },
          "fees_pct": {
            "type": [
              "number",
              "null"
            ]
          },
          "funding_pct": {
            "type": [
              "number",
              "null"
            ]
          },
          "slippage_pct": {
            "type": [
              "number",
              "null"
            ]
          },
          "committee_action": {
            "type": "string",
            "enum": [
              "long",
              "short"
            ],
            "description": "the committee's direction; identical to direction on sized calls"
          },
          "book_status": {
            "type": "string",
            "enum": [
              "sized",
              "sized_trimmed"
            ],
            "description": "whether exposure caps trimmed the fill"
          },
          "synthesis_conviction": {
            "type": [
              "number",
              "null"
            ],
            "description": "blended desk conviction at open; null for calls before the synthesis era"
          }
        }
      },
      "PredictionCall": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "const": "prediction"
          },
          "question": {
            "type": "string"
          },
          "side": {
            "type": "string",
            "enum": [
              "YES",
              "NO"
            ]
          },
          "confidence": {
            "type": "integer",
            "description": "stated probability, percent"
          },
          "implied_entry": {
            "type": [
              "number",
              "null"
            ],
            "description": "market-implied probability of the held side at call time"
          },
          "resolved": {
            "type": "boolean"
          },
          "correct": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "alpha_vs_market": {
            "type": [
              "number",
              "null"
            ],
            "description": "Brier edge vs the market's own price; positive beats the market"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "resolved_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Intelligence": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string"
          },
          "computed_at": {
            "type": "string",
            "format": "date-time"
          },
          "data_primary": {
            "type": "string",
            "description": "Venue serving this market's spot OHLCV, and so the substrate under every score in this payload. \"coinbase\" for most majors; markets Coinbase does not list name their own venue.",
            "example": "coinbase"
          },
          "composite_score": {
            "type": "number"
          },
          "direction": {
            "type": "string"
          },
          "trend_score": {
            "type": "number"
          },
          "momentum_score": {
            "type": "number"
          },
          "volatility_score": {
            "type": "number"
          },
          "volume_score": {
            "type": "number"
          },
          "key_signals": {
            "type": "object",
            "additionalProperties": true
          },
          "atr_value": {
            "type": [
              "number",
              "null"
            ]
          },
          "fng_value": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      }
    }
  }
}