Consensus Risk Signals
Contact
Developers

Developer API documentation

Everything you need to call the API and use the returned data in your own website or internal tools.

Public Preview API

Browser-safe, CORS-enabled, intentionally constrained. No auth.

Billing API

Stripe checkout + API key provisioning for subscribers.

Customer API

Full subscriber API protected by an API key (Bearer / X-API-Key).

Base URLs (how to point your site at the API)

The marketing website is static, so API origins are baked at build time:

Public API (preview + billing)
PUBLIC_API_BASE_URL (defaults to http://localhost:8000)
Customer API (subscriber)
PUBLIC_CUSTOMER_API_BASE_URL (no default; set in production)
Tip: the /live-preview/ page also supports a local override query string: ?api=http://localhost:8000.
Schemas + endpoint shapes (OpenAPI)

The most complete schema source-of-truth is each service’s OpenAPI spec. Below we render request/response shapes and schema descriptions directly from /openapi.json.

Public API spec
Base: https://polymarket-gvf-public-1002418729876.us-central1.run.app
Swagger UI openapi.json
5 paths · 7 schemas
Customer API spec
Base: https://polymarket-gvf-customer-xc6bbvvisq-uc.a.run.app
Swagger UI openapi.json
21 paths · 13 schemas
Public API endpoints
GET /health Health
Request body schema
No JSON body
200/201 response schema

                          {
  "title": "HealthResponse",
  "properties": {
    "status": {
      "type": "string",
      "title": "Status"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "title": "Timestamp"
    }
  },
  "type": "object",
  "required": [
    "status",
    "timestamp"
  ]
}
GET /api/v1/public/live-preview Live Preview
Return a limited, interpretive-friendly payload for the website's Live Preview. - Market set is capped (<=8). - Only a couple of signals/feature-derived values are returned. - Window is short (hours) and points are capped. - Query params are intentionally not supported (to keep it incomplete and cacheable).
Request body schema
No JSON body
200/201 response schema

                          {
  "additionalProperties": true,
  "type": "object",
  "title": "Response Live Preview Api V1 Public Live Preview Get"
}
POST /api/v1/billing/create-checkout-session Create Checkout Session
Create a Stripe Checkout Session for a monthly subscription. The website should redirect the user to the returned URL.
Request body schema

                          {
  "title": "CreateCheckoutSessionRequest",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "title": "Email"
    },
    "interval": {
      "type": "string",
      "enum": [
        "monthly",
        "yearly"
      ],
      "title": "Interval",
      "default": "monthly"
    }
  },
  "type": "object",
  "required": [
    "email"
  ]
}
200/201 response schema

                          {
  "title": "CreateCheckoutSessionResponse",
  "properties": {
    "url": {
      "type": "string",
      "title": "Url"
    }
  },
  "type": "object",
  "required": [
    "url"
  ]
}
POST /api/v1/billing/provision-api-key Provision Api Key
Provision an API key after successful checkout. This endpoint is designed to be called from the website's /subscribe/success/ page, using the session_id returned by Stripe in the success_url.
Request body schema

                          {
  "title": "ProvisionAPIKeyRequest",
  "properties": {
    "session_id": {
      "type": "string",
      "title": "Session Id"
    }
  },
  "type": "object",
  "required": [
    "session_id"
  ]
}
200/201 response schema

                          {
  "title": "ProvisionAPIKeyResponse",
  "properties": {
    "status": {
      "type": "string",
      "title": "Status"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Api Key"
    },
    "customer_email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Customer Email"
    }
  },
  "type": "object",
  "required": [
    "status"
  ]
}
POST /api/v1/billing/stripe/webhook Stripe Webhook
Stripe webhook handler to keep subscription status in sync.
Request body schema
No JSON body
200/201 response schema

                          {
  "type": "object",
  "additionalProperties": true,
  "title": "Response Stripe Webhook Api V1 Billing Stripe Webhook Post"
}
Public API schema glossary (components.schemas)
CreateCheckoutSessionRequest 
                    {
  "title": "CreateCheckoutSessionRequest",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "title": "Email"
    },
    "interval": {
      "type": "string",
      "enum": [
        "monthly",
        "yearly"
      ],
      "title": "Interval",
      "default": "monthly"
    }
  },
  "type": "object",
  "required": [
    "email"
  ]
}
CreateCheckoutSessionResponse 
                    {
  "title": "CreateCheckoutSessionResponse",
  "properties": {
    "url": {
      "type": "string",
      "title": "Url"
    }
  },
  "type": "object",
  "required": [
    "url"
  ]
}
HTTPValidationError 
                    {
  "title": "HTTPValidationError",
  "properties": {
    "detail": {
      "items": {
        "title": "ValidationError",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ]
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object"
}
HealthResponse 
                    {
  "title": "HealthResponse",
  "properties": {
    "status": {
      "type": "string",
      "title": "Status"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "title": "Timestamp"
    }
  },
  "type": "object",
  "required": [
    "status",
    "timestamp"
  ]
}
ProvisionAPIKeyRequest 
                    {
  "title": "ProvisionAPIKeyRequest",
  "properties": {
    "session_id": {
      "type": "string",
      "title": "Session Id"
    }
  },
  "type": "object",
  "required": [
    "session_id"
  ]
}
ProvisionAPIKeyResponse 
                    {
  "title": "ProvisionAPIKeyResponse",
  "properties": {
    "status": {
      "type": "string",
      "title": "Status"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Api Key"
    },
    "customer_email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Customer Email"
    }
  },
  "type": "object",
  "required": [
    "status"
  ]
}
ValidationError 
                    {
  "title": "ValidationError",
  "properties": {
    "loc": {
      "items": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "integer"
          }
        ]
      },
      "type": "array",
      "title": "Location"
    },
    "msg": {
      "type": "string",
      "title": "Message"
    },
    "type": {
      "type": "string",
      "title": "Error Type"
    }
  },
  "type": "object",
  "required": [
    "loc",
    "msg",
    "type"
  ]
}
Customer API endpoints
GET /health Health
Request body schema
No JSON body
200/201 response schema

                          {
  "title": "HealthResponse",
  "properties": {
    "status": {
      "type": "string",
      "title": "Status"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "title": "Timestamp"
    }
  },
  "type": "object",
  "required": [
    "status",
    "timestamp"
  ]
}
GET /markets List Markets
List markets with optional filters.
Request body schema
No JSON body
200/201 response schema

                          {
  "type": "array",
  "items": {
    "title": "MarketResponse",
    "properties": {
      "id": {
        "type": "string",
        "title": "Id"
      },
      "question": {
        "type": "string",
        "title": "Question"
      },
      "category": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Category"
      },
      "end_time": {
        "anyOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ],
        "title": "End Time"
      },
      "created_at": {
        "anyOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ],
        "title": "Created At"
      },
      "closed": {
        "type": "boolean",
        "title": "Closed"
      },
      "archived": {
        "type": "boolean",
        "title": "Archived"
      },
      "liquidity": {
        "type": "number",
        "title": "Liquidity"
      },
      "volume": {
        "type": "number",
        "title": "Volume"
      }
    },
    "type": "object",
    "required": [
      "id",
      "question",
      "category",
      "end_time",
      "created_at",
      "closed",
      "archived",
      "liquidity",
      "volume"
    ],
    "description": "Market response model."
  },
  "title": "Response List Markets Markets Get"
}
GET /markets/{market_id}/signals Get Market Signals
Get signals for a specific market.
Request body schema
No JSON body
200/201 response schema

                          {
  "type": "array",
  "items": {
    "title": "SignalResponse",
    "properties": {
      "market_id": {
        "type": "string",
        "title": "Market Id"
      },
      "timestamp": {
        "type": "string",
        "format": "date-time",
        "title": "Timestamp"
      },
      "signals": {
        "additionalProperties": {
          "type": "number"
        },
        "type": "object",
        "title": "Signals"
      }
    },
    "type": "object",
    "required": [
      "market_id",
      "timestamp",
      "signals"
    ],
    "description": "Signal response model."
  },
  "title": "Response Get Market Signals Markets  Market Id  Signals Get"
}
GET /markets/{market_id}/snapshots Get Market Snapshots
Get snapshots for a specific market.
Request body schema
No JSON body
200/201 response schema

                          {
  "type": "array",
  "items": {
    "type": "object",
    "additionalProperties": true
  },
  "title": "Response Get Market Snapshots Markets  Market Id  Snapshots Get"
}
GET /indexes List Indexes
List available index names.
Request body schema
No JSON body
200/201 response schema

                          {
  "items": {
    "type": "string"
  },
  "type": "array",
  "title": "Response List Indexes Indexes Get"
}
GET /indexes/{index_name} Get Index History
Get index history.
Request body schema
No JSON body
200/201 response schema

                          {
  "type": "array",
  "items": {
    "title": "IndexResponse",
    "properties": {
      "index_name": {
        "type": "string",
        "title": "Index Name"
      },
      "timestamp": {
        "type": "string",
        "format": "date-time",
        "title": "Timestamp"
      },
      "value": {
        "type": "number",
        "title": "Value"
      },
      "metadata": {
        "anyOf": [
          {
            "additionalProperties": true,
            "type": "object"
          },
          {
            "type": "null"
          }
        ],
        "title": "Metadata"
      }
    },
    "type": "object",
    "required": [
      "index_name",
      "timestamp",
      "value"
    ],
    "description": "Index response model."
  },
  "title": "Response Get Index History Indexes  Index Name  Get"
}
GET /markets/{market_id}/explain Explain Market
Explain current signals + feature drivers + model contributions for a market/candidate.
Request body schema
No JSON body
200/201 response schema

                          {}
GET /api/v1/gvfs/candidates List Candidates
Request body schema
No JSON body
200/201 response schema

                          {
  "type": "array",
  "items": {
    "title": "GVFCandidateResponse",
    "properties": {
      "id": {
        "type": "integer",
        "title": "Id"
      },
      "name": {
        "type": "string",
        "title": "Name"
      },
      "description": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Description"
      },
      "target_def": {
        "additionalProperties": true,
        "type": "object",
        "title": "Target Def"
      },
      "horizon_minutes": {
        "type": "integer",
        "title": "Horizon Minutes"
      },
      "enabled": {
        "type": "boolean",
        "title": "Enabled"
      }
    },
    "type": "object",
    "required": [
      "id",
      "name",
      "target_def",
      "horizon_minutes",
      "enabled"
    ]
  },
  "title": "Response List Candidates Api V1 Gvfs Candidates Get"
}
GET /api/v1/gvfs/candidates/{candidate_id}/evals Get Candidate Evals
Request body schema
No JSON body
200/201 response schema

                          {
  "type": "array",
  "items": {
    "title": "GVFEvalResponse",
    "properties": {
      "candidate_id": {
        "type": "integer",
        "title": "Candidate Id"
      },
      "timestamp": {
        "type": "string",
        "format": "date-time",
        "title": "Timestamp"
      },
      "temporal_uniformity": {
        "type": "number",
        "title": "Temporal Uniformity"
      },
      "usefulness": {
        "type": "number",
        "title": "Usefulness"
      },
      "drift": {
        "type": "number",
        "title": "Drift"
      },
      "regime_robustness": {
        "type": "number",
        "title": "Regime Robustness"
      },
      "composite": {
        "type": "number",
        "title": "Composite"
      },
      "eval_metadata": {
        "anyOf": [
          {
            "additionalProperties": true,
            "type": "object"
          },
          {
            "type": "null"
          }
        ],
        "title": "Eval Metadata"
      }
    },
    "type": "object",
    "required": [
      "candidate_id",
      "timestamp",
      "temporal_uniformity",
      "usefulness",
      "drift",
      "regime_robustness",
      "composite"
    ]
  },
  "title": "Response Get Candidate Evals Api V1 Gvfs Candidates  Candidate Id  Evals Get"
}
GET /api/v1/gvfs/discovered_indexes List Discovered Indexes
Request body schema
No JSON body
200/201 response schema

                          {
  "type": "array",
  "items": {
    "title": "DiscoveredIndexResponse",
    "properties": {
      "index_name": {
        "type": "string",
        "title": "Index Name"
      },
      "candidate_id": {
        "type": "integer",
        "title": "Candidate Id"
      },
      "status": {
        "type": "string",
        "title": "Status"
      },
      "promoted_at": {
        "anyOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ],
        "title": "Promoted At"
      },
      "retired_at": {
        "anyOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ],
        "title": "Retired At"
      },
      "last_score": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "null"
          }
        ],
        "title": "Last Score"
      },
      "thresholds": {
        "anyOf": [
          {
            "additionalProperties": true,
            "type": "object"
          },
          {
            "type": "null"
          }
        ],
        "title": "Thresholds"
      }
    },
    "type": "object",
    "required": [
      "index_name",
      "candidate_id",
      "status"
    ]
  },
  "title": "Response List Discovered Indexes Api V1 Gvfs Discovered Indexes Get"
}
GET /api/v1/mutation/scenarios List Scenarios
Request body schema
No JSON body
200/201 response schema

                          {
  "items": {
    "type": "string"
  },
  "type": "array",
  "title": "Response List Scenarios Api V1 Mutation Scenarios Get"
}
GET /api/v1/mutation/summary Mutation Summary
Request body schema
No JSON body
200/201 response schema

                          {}
GET /api/v1/mutation/beats Mutated Beats Legacy
Compute 'mutated beats legacy' with eligibility gating + deltas over time. Eligibility: - Uses per-market gvf_evals rows (market_id NOT NULL) where n_obs >= min_obs - Candidate must have >= min_markets distinct markets in the bucket - Candidate score for the bucket is avg(composite_score) over eligible markets Comparison: - For each bucket timestamp, take top_k candidates by score within each population - population_score = average(score of top_k) (more stable than top-1) - delta = mutated_score - legacy_score
Request body schema
No JSON body
200/201 response schema

                          {}
GET /api/v1/consensus/scenarios List Scenarios
Request body schema
No JSON body
200/201 response schema

                          {
  "items": {
    "type": "string"
  },
  "type": "array",
  "title": "Response List Scenarios Api V1 Consensus Scenarios Get"
}
GET /api/v1/consensus/markets List Markets
Request body schema
No JSON body
200/201 response schema

                          {
  "type": "array",
  "items": {
    "type": "string"
  },
  "title": "Response List Markets Api V1 Consensus Markets Get"
}
GET /api/v1/consensus/series Market Series
Request body schema
No JSON body
200/201 response schema

                          {}
GET /api/v1/consensus/validation Validation Summary
Compute MVP validation checks from a consensus validation scenario DB.
Request body schema
No JSON body
200/201 response schema

                          {}
GET /api/v1/webhooks/events List Event Types
List available webhook event types.
Request body schema
No JSON body
200/201 response schema

                          {
  "items": {
    "type": "string"
  },
  "type": "array",
  "title": "Response List Event Types Api V1 Webhooks Events Get"
}
POST /api/v1/webhooks Create Webhook
Register a new webhook.
Request body schema

                          {
  "title": "WebhookCreate",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2083,
      "minLength": 1,
      "format": "uri",
      "title": "Url"
    },
    "events": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Events"
    },
    "secret": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Secret"
    }
  },
  "type": "object",
  "required": [
    "url",
    "events"
  ],
  "description": "Webhook creation request."
}
200/201 response schema

                          {
  "title": "WebhookResponse",
  "properties": {
    "id": {
      "type": "integer",
      "title": "Id"
    },
    "url": {
      "type": "string",
      "title": "Url"
    },
    "events": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Events"
    },
    "active": {
      "type": "boolean",
      "title": "Active"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "title": "Created At"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "title": "Updated At"
    }
  },
  "type": "object",
  "required": [
    "id",
    "url",
    "events",
    "active",
    "created_at",
    "updated_at"
  ],
  "description": "Webhook response model."
}
GET /api/v1/webhooks List Webhooks
List all webhooks.
Request body schema
No JSON body
200/201 response schema

                          {
  "type": "array",
  "items": {
    "title": "WebhookResponse",
    "properties": {
      "id": {
        "type": "integer",
        "title": "Id"
      },
      "url": {
        "type": "string",
        "title": "Url"
      },
      "events": {
        "items": {
          "type": "string"
        },
        "type": "array",
        "title": "Events"
      },
      "active": {
        "type": "boolean",
        "title": "Active"
      },
      "created_at": {
        "type": "string",
        "format": "date-time",
        "title": "Created At"
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "title": "Updated At"
      }
    },
    "type": "object",
    "required": [
      "id",
      "url",
      "events",
      "active",
      "created_at",
      "updated_at"
    ],
    "description": "Webhook response model."
  },
  "title": "Response List Webhooks Api V1 Webhooks Get"
}
GET /api/v1/webhooks/{webhook_id} Get Webhook
Get webhook by ID.
Request body schema
No JSON body
200/201 response schema

                          {
  "title": "WebhookResponse",
  "properties": {
    "id": {
      "type": "integer",
      "title": "Id"
    },
    "url": {
      "type": "string",
      "title": "Url"
    },
    "events": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Events"
    },
    "active": {
      "type": "boolean",
      "title": "Active"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "title": "Created At"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "title": "Updated At"
    }
  },
  "type": "object",
  "required": [
    "id",
    "url",
    "events",
    "active",
    "created_at",
    "updated_at"
  ],
  "description": "Webhook response model."
}
PATCH /api/v1/webhooks/{webhook_id} Update Webhook
Update webhook.
Request body schema

                          {
  "title": "WebhookUpdate",
  "properties": {
    "url": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2083,
          "minLength": 1,
          "format": "uri"
        },
        {
          "type": "null"
        }
      ],
      "title": "Url"
    },
    "events": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Events"
    },
    "active": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Active"
    }
  },
  "type": "object",
  "description": "Webhook update request."
}
200/201 response schema

                          {
  "title": "WebhookResponse",
  "properties": {
    "id": {
      "type": "integer",
      "title": "Id"
    },
    "url": {
      "type": "string",
      "title": "Url"
    },
    "events": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Events"
    },
    "active": {
      "type": "boolean",
      "title": "Active"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "title": "Created At"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "title": "Updated At"
    }
  },
  "type": "object",
  "required": [
    "id",
    "url",
    "events",
    "active",
    "created_at",
    "updated_at"
  ],
  "description": "Webhook response model."
}
DELETE /api/v1/webhooks/{webhook_id} Delete Webhook
Delete webhook.
Request body schema
No JSON body
200/201 response schema
No JSON body
POST /api/v1/webhooks/{webhook_id}/test Test Webhook
Test webhook delivery.
Request body schema

                          {
  "title": "WebhookTestRequest",
  "properties": {
    "event_type": {
      "type": "string",
      "title": "Event Type",
      "default": "signal.created"
    },
    "payload": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Payload"
    }
  },
  "type": "object",
  "description": "Webhook test request."
}
200/201 response schema

                          {}
Customer API schema glossary (components.schemas)
DiscoveredIndexResponse 
                    {
  "title": "DiscoveredIndexResponse",
  "properties": {
    "index_name": {
      "type": "string",
      "title": "Index Name"
    },
    "candidate_id": {
      "type": "integer",
      "title": "Candidate Id"
    },
    "status": {
      "type": "string",
      "title": "Status"
    },
    "promoted_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Promoted At"
    },
    "retired_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Retired At"
    },
    "last_score": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Last Score"
    },
    "thresholds": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Thresholds"
    }
  },
  "type": "object",
  "required": [
    "index_name",
    "candidate_id",
    "status"
  ]
}
GVFCandidateResponse 
                    {
  "title": "GVFCandidateResponse",
  "properties": {
    "id": {
      "type": "integer",
      "title": "Id"
    },
    "name": {
      "type": "string",
      "title": "Name"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Description"
    },
    "target_def": {
      "additionalProperties": true,
      "type": "object",
      "title": "Target Def"
    },
    "horizon_minutes": {
      "type": "integer",
      "title": "Horizon Minutes"
    },
    "enabled": {
      "type": "boolean",
      "title": "Enabled"
    }
  },
  "type": "object",
  "required": [
    "id",
    "name",
    "target_def",
    "horizon_minutes",
    "enabled"
  ]
}
GVFEvalResponse 
                    {
  "title": "GVFEvalResponse",
  "properties": {
    "candidate_id": {
      "type": "integer",
      "title": "Candidate Id"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "title": "Timestamp"
    },
    "temporal_uniformity": {
      "type": "number",
      "title": "Temporal Uniformity"
    },
    "usefulness": {
      "type": "number",
      "title": "Usefulness"
    },
    "drift": {
      "type": "number",
      "title": "Drift"
    },
    "regime_robustness": {
      "type": "number",
      "title": "Regime Robustness"
    },
    "composite": {
      "type": "number",
      "title": "Composite"
    },
    "eval_metadata": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Eval Metadata"
    }
  },
  "type": "object",
  "required": [
    "candidate_id",
    "timestamp",
    "temporal_uniformity",
    "usefulness",
    "drift",
    "regime_robustness",
    "composite"
  ]
}
HTTPValidationError 
                    {
  "title": "HTTPValidationError",
  "properties": {
    "detail": {
      "items": {
        "title": "ValidationError",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ]
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object"
}
HealthResponse 
                    {
  "title": "HealthResponse",
  "properties": {
    "status": {
      "type": "string",
      "title": "Status"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "title": "Timestamp"
    }
  },
  "type": "object",
  "required": [
    "status",
    "timestamp"
  ]
}
IndexResponse 
                    {
  "title": "IndexResponse",
  "properties": {
    "index_name": {
      "type": "string",
      "title": "Index Name"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "title": "Timestamp"
    },
    "value": {
      "type": "number",
      "title": "Value"
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Metadata"
    }
  },
  "type": "object",
  "required": [
    "index_name",
    "timestamp",
    "value"
  ],
  "description": "Index response model."
}
MarketResponse 
                    {
  "title": "MarketResponse",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id"
    },
    "question": {
      "type": "string",
      "title": "Question"
    },
    "category": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Category"
    },
    "end_time": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "End Time"
    },
    "created_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Created At"
    },
    "closed": {
      "type": "boolean",
      "title": "Closed"
    },
    "archived": {
      "type": "boolean",
      "title": "Archived"
    },
    "liquidity": {
      "type": "number",
      "title": "Liquidity"
    },
    "volume": {
      "type": "number",
      "title": "Volume"
    }
  },
  "type": "object",
  "required": [
    "id",
    "question",
    "category",
    "end_time",
    "created_at",
    "closed",
    "archived",
    "liquidity",
    "volume"
  ],
  "description": "Market response model."
}
SignalResponse 
                    {
  "title": "SignalResponse",
  "properties": {
    "market_id": {
      "type": "string",
      "title": "Market Id"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "title": "Timestamp"
    },
    "signals": {
      "additionalProperties": {
        "type": "number"
      },
      "type": "object",
      "title": "Signals"
    }
  },
  "type": "object",
  "required": [
    "market_id",
    "timestamp",
    "signals"
  ],
  "description": "Signal response model."
}
ValidationError 
                    {
  "title": "ValidationError",
  "properties": {
    "loc": {
      "items": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "integer"
          }
        ]
      },
      "type": "array",
      "title": "Location"
    },
    "msg": {
      "type": "string",
      "title": "Message"
    },
    "type": {
      "type": "string",
      "title": "Error Type"
    }
  },
  "type": "object",
  "required": [
    "loc",
    "msg",
    "type"
  ]
}
WebhookCreate 
                    {
  "title": "WebhookCreate",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2083,
      "minLength": 1,
      "format": "uri",
      "title": "Url"
    },
    "events": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Events"
    },
    "secret": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Secret"
    }
  },
  "type": "object",
  "required": [
    "url",
    "events"
  ],
  "description": "Webhook creation request."
}
WebhookResponse 
                    {
  "title": "WebhookResponse",
  "properties": {
    "id": {
      "type": "integer",
      "title": "Id"
    },
    "url": {
      "type": "string",
      "title": "Url"
    },
    "events": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Events"
    },
    "active": {
      "type": "boolean",
      "title": "Active"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "title": "Created At"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "title": "Updated At"
    }
  },
  "type": "object",
  "required": [
    "id",
    "url",
    "events",
    "active",
    "created_at",
    "updated_at"
  ],
  "description": "Webhook response model."
}
WebhookTestRequest 
                    {
  "title": "WebhookTestRequest",
  "properties": {
    "event_type": {
      "type": "string",
      "title": "Event Type",
      "default": "signal.created"
    },
    "payload": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Payload"
    }
  },
  "type": "object",
  "description": "Webhook test request."
}
WebhookUpdate 
                    {
  "title": "WebhookUpdate",
  "properties": {
    "url": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2083,
          "minLength": 1,
          "format": "uri"
        },
        {
          "type": "null"
        }
      ],
      "title": "Url"
    },
    "events": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Events"
    },
    "active": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Active"
    }
  },
  "type": "object",
  "description": "Webhook update request."
}
Authentication

Only the Customer API requires auth.

Header (recommended)
Authorization: Bearer <YOUR_API_KEY>
Alternative header
X-API-Key: <YOUR_API_KEY>
Keep API keys out of client-side code unless you are okay with end-users having that access. For public websites, proxy requests through your server.
Public Preview API (no auth)
A small, cacheable payload designed for website embeds and demos (not a full dashboard).
Endpoint
GET /api/v1/public/live-preview
Rate limit: 30 requests/min per IP. Uses ETag and cache headers to encourage reuse.
Shape (high level)
{
  "kind": "live_signal_preview_v1",
  "generated_at": "2025-01-01T00:00:00+00:00",
  "window": { "since": "...", "hours": 72, "points": 96 },
  "markets": [
    {
      "market_id": "...",
      "question": "...",
      "category": "...",
      "status": "ok | cold_start | no_data",
      "asof": { "compression_z": 0.4, "surprise_risk": 0.12, "surprise_confidence": 0.8 },
      "series": { "compression": [{ "ts": "...", "compression_z": 0.1 }], "surprise": [{ "ts": "...", "surprise_risk": 0.2, "surprise_confidence": 0.7 }] }
    }
  ]
}
Browser example (fetch + render)
const API_BASE = "https://YOUR_PUBLIC_API";

const resp = await fetch(`${API_BASE}/api/v1/public/live-preview`);
if (!resp.ok) throw new Error(await resp.text());
const data = await resp.json();

// Example: build a simple list of titles + latest values
const rows = (data.markets || []).map((m) => ({
  id: m.market_id,
  question: m.question,
  compressionZ: m.asof?.compression_z,
  surpriseRisk: m.asof?.surprise_risk,
}));

console.log(rows);
Note: query params are intentionally ignored by this endpoint to keep it cacheable and prevent “free dashboard” usage.
Billing API (checkout + API key provisioning)

Used by the website’s subscription flow. These endpoints live on the Public API service.

Create checkout session
POST /api/v1/billing/create-checkout-session
{
  "email": "you@company.com"
}
Returns {"url":"https://checkout.stripe.com/..."} for the browser to redirect to.
Provision API key (shown once)
POST /api/v1/billing/provision-api-key
{
  "session_id": "cs_test_..."
}
Returns status="ok" with api_key, or status="already_provisioned".
Stripe webhooks are handled at POST /api/v1/billing/stripe/webhook (server-to-server).
Customer API (subscriber)

Full API surface for markets, signals, snapshots, indexes, explainability, GVF discovery, and webhooks. Requires API key.

Test auth
curl -sS \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  "https://YOUR_CUSTOMER_API/health"
Rate limits
Daily per-org usage limit is enforced (default 10000 requests/day), configured by CUSTOMER_API_DAILY_LIMIT.
Markets
GET /markets?category=&closed=&limit=
GET /markets/<market_id>/signals?since=&limit=
GET /markets/<market_id>/snapshots?since=&limit=
Indexes + explain
GET /indexes
GET /indexes/hidden_info_index?since=&limit=
GET /markets/<market_id>/explain?candidate_id=&top_k=
GVF discovery
GET /api/v1/gvfs/candidates?enabled_only=true
GET /api/v1/gvfs/candidates/<id>/evals?since=&limit=
GET /api/v1/gvfs/discovered_indexes?active_only=true
Webhooks (optional)
GET /api/v1/webhooks/events
POST /api/v1/webhooks
PATCH /api/v1/webhooks/<id>
POST /api/v1/webhooks/<id>/test
Using the data on your website
Common pattern: overlay
Join the signal series to your existing market cards/charts: show the latest asof values and a small sparkline from series.
Common pattern: alerts
Poll at 30–60s, only when the tab is visible. Trigger UI highlights when values cross your thresholds.
For interactive docs, each service also exposes FastAPI’s OpenAPI UI at /docs and a spec at /openapi.json.
See live preview API & Dashboard Request access