{ "openapi": "3.1.0", "info": { "title": "Upvera Value API", "version": "1.0.0", "description": "Read-only public API for Upvera Value: every startup's value, its series, the receipt that explains each change and the Upvera Index. Values come from the server as they are shown on app.upvera.co/value; nothing is a price quote or an offer. Fields are only ever added; a breaking change ships as /api/v2. Rate limit: 60 requests per minute per IP. Cache: public, max-age=30, s-maxage=60, stale-while-revalidate=300. CORS: any origin. With an API key (Scale plan; create it in Upvera › Connections › Value API): send Authorization: Bearer upv_live_… from your server, 600 requests per minute per key, responses are private (not shared-cached), and /api/v1/me endpoints open. Keys never go in the URL; browsers cannot send them (CORS does not allow the Authorization header). Webhooks: signed POSTs when your startup's value crosses your threshold (see `webhooks`); verify Upvera-Signature (t=…,v1=HMAC-SHA256(secret, t + '.' + body)) and reject timestamps older than 5 minutes." }, "servers": [ { "url": "https://app.upvera.co" } ], "security": [ {}, { "apiKey": [] } ], "paths": { "/api/v1/startups": { "get": { "operationId": "listStartups", "summary": "Startups in Ranks, by rank", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d" ], "default": "24h" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "v", "kind", "as_of", "state", "data" ], "properties": { "v": { "const": "upvera/api/v1" }, "kind": { "const": "startups" }, "as_of": { "type": "string", "format": "date-time" }, "state": { "enum": [ "legacy", "v3" ], "description": "Value method in force: v3 = Value Engine 3.0." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StartupRow" } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/startups/{slug}": { "get": { "operationId": "getStartup", "summary": "One startup's Upvera Value and changes", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "v", "kind", "as_of", "state", "data" ], "properties": { "v": { "const": "upvera/api/v1" }, "kind": { "const": "startup" }, "as_of": { "type": "string", "format": "date-time" }, "state": { "enum": [ "legacy", "v3" ], "description": "Value method in force: v3 = Value Engine 3.0." }, "data": { "$ref": "#/components/schemas/Startup" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/startups/{slug}/series": { "get": { "operationId": "getSeries", "summary": "Upvera Value series", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$" } }, { "name": "window", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "all" ], "default": "7d" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "v", "kind", "as_of", "state", "data" ], "properties": { "v": { "const": "upvera/api/v1" }, "kind": { "const": "series" }, "as_of": { "type": "string", "format": "date-time" }, "state": { "enum": [ "legacy", "v3" ], "description": "Value method in force: v3 = Value Engine 3.0." }, "data": { "$ref": "#/components/schemas/Series" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/startups/{slug}/receipt": { "get": { "operationId": "getReceipt", "summary": "Why the value changed: the receipt for a window", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$" } }, { "name": "window", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "all" ], "default": "24h" } }, { "name": "lang", "in": "query", "required": false, "schema": { "enum": [ "en", "tr" ], "default": "en" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "v", "kind", "as_of", "state", "data" ], "properties": { "v": { "const": "upvera/api/v1" }, "kind": { "const": "receipt" }, "as_of": { "type": "string", "format": "date-time" }, "state": { "enum": [ "legacy", "v3" ], "description": "Value method in force: v3 = Value Engine 3.0." }, "data": { "$ref": "#/components/schemas/ReceiptData" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/index": { "get": { "operationId": "getIndex", "summary": "Upvera Index, or a category index (categories with at least 3 members)", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "enum": [ "7d", "30d", "all" ], "default": "30d" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "v", "kind", "as_of", "state", "data" ], "properties": { "v": { "const": "upvera/api/v1" }, "kind": { "const": "index" }, "as_of": { "type": "string", "format": "date-time" }, "state": { "enum": [ "legacy", "v3" ], "description": "Value method in force: v3 = Value Engine 3.0." }, "data": { "$ref": "#/components/schemas/Index" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/me": { "get": { "operationId": "getMe", "summary": "The API key's owner: their startups (current value) and webhooks", "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "v", "kind", "as_of", "state", "data" ], "properties": { "v": { "const": "upvera/api/v1" }, "kind": { "const": "me" }, "as_of": { "type": "string", "format": "date-time" }, "state": { "enum": [ "legacy", "v3" ], "description": "Value method in force: v3 = Value Engine 3.0." }, "data": { "$ref": "#/components/schemas/Me" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/me/deliveries": { "get": { "operationId": "listDeliveries", "summary": "Recent webhook deliveries across the owner's endpoints (status only, no bodies)", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "v", "kind", "as_of", "state", "data" ], "properties": { "v": { "const": "upvera/api/v1" }, "kind": { "const": "deliveries" }, "as_of": { "type": "string", "format": "date-time" }, "state": { "enum": [ "legacy", "v3" ], "description": "Value method in force: v3 = Value Engine 3.0." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "value.threshold": { "post": { "summary": "Your startup's Upvera Value moved by at least your threshold since the last notification", "description": "Sent at most every 5 minutes per startup, only in the direction you chose. The anchor moves on every threshold crossing in either direction. At-least-once: deduplicate on the event id (also in the Upvera-Event-Id header). Retries back off from 1 minute to 6 hours, 12 attempts in about a day.", "parameters": [ { "name": "Upvera-Signature", "in": "header", "required": true, "schema": { "type": "string", "example": "t=1760834640,v1=5f2b…" } }, { "name": "Upvera-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery; anything else is retried." } } } }, "ping": { "post": { "summary": "Sent when you add an endpoint or press Send test", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "upv_live_…", "description": "Scale plan API key. Server-side only." } }, "schemas": { "Error": { "type": "object", "properties": { "v": { "const": "upvera/api/v1" }, "error": { "type": "object", "properties": { "code": { "enum": [ "bad_request", "unauthorized", "plan_required", "not_found", "rate_limited", "unavailable" ] }, "message": { "type": "string" } } } } }, "Me": { "type": "object", "properties": { "key": { "type": "object", "properties": { "prefix": { "type": "string" }, "last4": { "type": "string" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_per_min": { "type": "integer" }, "expires_at": { "type": [ "string", "null" ], "description": "Set while a rotated key keeps working for 24 hours." }, "created_at": { "type": "string" } } }, "owner": { "type": "object", "properties": { "username": { "type": [ "string", "null" ] } } }, "startups": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "urls": { "$ref": "#/components/schemas/Urls" } } } }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "host": { "type": "string" }, "threshold_pct": { "type": "number" }, "direction": { "enum": [ "up", "down", "both" ] }, "status": { "enum": [ "active", "paused", "failing" ] }, "last_ok_at": { "type": [ "string", "null" ] }, "last_fail_at": { "type": [ "string", "null" ] } } } } } }, "Delivery": { "type": "object", "properties": { "event_id": { "type": "string" }, "type": { "enum": [ "value.threshold", "ping" ] }, "webhook": { "type": "object", "properties": { "id": { "type": "string" }, "host": { "type": "string" } } }, "startup": { "type": [ "string", "null" ], "description": "Startup slug (value.threshold)." }, "change_pct": { "type": [ "number", "null" ] }, "state": { "enum": [ "pending", "retrying", "ok", "dead", "skipped" ] }, "attempts": { "type": "integer" }, "code": { "type": [ "integer", "null" ], "description": "Your endpoint's HTTP status." }, "error": { "type": [ "string", "null" ], "description": "timeout · dns · tls · network · redirect · http_status · blocked_address · invalid_url · paused · suspended · failing" }, "ms": { "type": [ "integer", "null" ] }, "created_at": { "type": "string" }, "last_at": { "type": [ "string", "null" ] } } }, "WebhookEvent": { "type": "object", "properties": { "v": { "const": "upvera/webhook/v1" }, "id": { "type": "string", "description": "evt_…, stable across retries." }, "type": { "enum": [ "value.threshold", "ping" ] }, "created_at": { "type": "string" }, "data": { "type": "object", "description": "value.threshold: startup · value · from · change_pct · direction · threshold_pct · as_of · from_at · rule. ping: webhook.", "properties": { "startup": { "type": "object", "properties": { "slug": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "url": { "type": [ "string", "null" ] } } }, "value": { "type": "number", "description": "Upvera Value now (unitless)." }, "from": { "type": "number", "description": "Value at the anchor (the last notification, or when you added the endpoint)." }, "change_pct": { "type": "number", "description": "Computed by Upvera, 2 decimals." }, "direction": { "enum": [ "up", "down" ] }, "threshold_pct": { "type": "number" }, "as_of": { "type": "string" }, "from_at": { "type": "string" }, "rule": { "type": "string", "description": "Value method in force, e.g. value@1." }, "webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "threshold_pct": { "type": "number" }, "direction": { "enum": [ "up", "down", "both" ] } } } } } } }, "Urls": { "type": "object", "properties": { "page": { "type": "string" }, "value": { "type": "string" }, "badge": { "type": "string" } } }, "StartupRow": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "tagline": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "rank": { "type": "integer" }, "value": { "type": [ "number", "null" ], "description": "Upvera Value (unitless)." }, "change": { "type": [ "object", "null" ], "properties": { "window": { "type": "string" }, "pct": { "type": "number" } } }, "wings": { "type": "integer", "description": "People with an active wing (count only)." }, "is_new": { "type": "boolean" }, "urls": { "$ref": "#/components/schemas/Urls" } } }, "Startup": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "tagline": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "rank": { "type": "integer" }, "rank_of": { "type": "integer" }, "value": { "type": [ "number", "null" ] }, "changes": { "type": "object", "properties": { "24h": { "type": [ "number", "null" ] }, "7d": { "type": [ "number", "null" ] }, "30d": { "type": [ "number", "null" ] } } }, "since_method": { "type": [ "object", "null" ], "description": "Change since the current method's first evaluation.", "properties": { "from": { "type": "string" }, "pct": { "type": [ "number", "null" ] } } }, "wings": { "type": [ "object", "null" ], "properties": { "count": { "type": "integer" }, "total_upv": { "type": "number", "description": "Total of active wings (aggregate only)." } } }, "entered_at": { "type": [ "string", "null" ] }, "urls": { "$ref": "#/components/schemas/Urls" } } }, "Series": { "type": "object", "properties": { "slug": { "type": "string" }, "window": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "points": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "number" } ] } } } }, "ReceiptData": { "type": "object", "properties": { "slug": { "type": "string" }, "window": { "type": "string" }, "receipt": { "type": [ "object", "null" ], "description": "null while no receipt exists for the method in force.", "properties": { "kind": { "enum": [ "window", "range" ] }, "since_method": { "type": "boolean" }, "from_at": { "type": "string" }, "from": { "type": "number" }, "to": { "type": "number" }, "change_e6": { "type": "integer", "description": "Exact change ×10⁶; the rows add up to it." }, "change": { "type": "number" }, "reasons": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Permanent reason code, e.g. value.work.events; value.lag is the catch-up row." }, "column": { "type": "string" }, "value_e6": { "type": "integer" }, "value": { "type": "number" }, "n": { "type": "integer" }, "label": { "type": "string" }, "text": { "type": "string" } } } }, "rule": { "type": [ "string", "null" ] }, "engine": { "type": [ "string", "null" ] }, "inputs": { "type": [ "string", "null" ], "description": "First 8 hex digits of the inputs hash." } } } } }, "Index": { "type": "object", "properties": { "name": { "const": "upvera" }, "category": { "type": [ "string", "null" ] }, "window": { "type": "string" }, "base": { "type": "object", "properties": { "day": { "type": "string" }, "value": { "const": 1000 } } }, "members": { "type": "integer" }, "value": { "type": [ "number", "null" ] }, "change_pct": { "type": [ "number", "null" ] }, "points": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "number" } ] } }, "breaks": { "type": "array", "description": "Days where a method change was taken out of the chain.", "items": { "type": "object", "properties": { "day": { "type": "string" }, "rules": { "type": "array", "items": { "type": "string" } }, "n": { "type": "integer" } } } } } } } } }