# Reference

Base URL `https://app.upvera.co`. Every response is wrapped in the same envelope: `v`, `kind`, `as_of`, `state` and `data`. This page is generated from the [OpenAPI document](/openapi.json), so it always matches the API.

## Startups in Ranks, by rank

```text
GET /api/v1/startups
```

| Parameter | In | | Values | Default |
|---|---|---|---|---|
| `window` | query | optional | `24h` · `7d` · `30d` | `24h` |

Returns `kind: "startups"` with `data` as array of [StartupRow](#startuprow).

Errors: `400` · `401` · `403` · `404` · `429` · `503`.

## One startup's Upvera Value and changes

```text
GET /api/v1/startups/{slug}
```

| Parameter | In | | Values | Default |
|---|---|---|---|---|
| `slug` | path | required | string, `^[a-z0-9][a-z0-9-]{0,79}$` |  |

Returns `kind: "startup"` with `data` as [Startup](#startup).

Errors: `400` · `401` · `403` · `404` · `429` · `503`.

## Upvera Value series

```text
GET /api/v1/startups/{slug}/series
```

| Parameter | In | | Values | Default |
|---|---|---|---|---|
| `slug` | path | required | string, `^[a-z0-9][a-z0-9-]{0,79}$` |  |
| `window` | query | optional | `24h` · `7d` · `30d` · `all` | `7d` |

Returns `kind: "series"` with `data` as [Series](#series).

Errors: `400` · `401` · `403` · `404` · `429` · `503`.

## Why the value changed: the receipt for a window

```text
GET /api/v1/startups/{slug}/receipt
```

| Parameter | In | | Values | Default |
|---|---|---|---|---|
| `slug` | path | required | string, `^[a-z0-9][a-z0-9-]{0,79}$` |  |
| `window` | query | optional | `24h` · `7d` · `30d` · `all` | `24h` |
| `lang` | query | optional | `en` · `tr` | `en` |

Returns `kind: "receipt"` with `data` as [ReceiptData](#receiptdata).

Errors: `400` · `401` · `403` · `404` · `429` · `503`.

## Upvera Index, or a category index (categories with at least 3 members)

```text
GET /api/v1/index
```

| Parameter | In | | Values | Default |
|---|---|---|---|---|
| `window` | query | optional | `7d` · `30d` · `all` | `30d` |
| `category` | query | optional | string |  |

Returns `kind: "index"` with `data` as [Index](#index).

Errors: `400` · `401` · `403` · `404` · `429` · `503`.

## The API key's owner: their startups (current value) and webhooks

```text
GET /api/v1/me
```

Requires an API key: `Authorization: Bearer upv_live_…`, from your server.

Returns `kind: "me"` with `data` as [Me](#me).

Errors: `400` · `401` · `403` · `429` · `503`.

## Recent webhook deliveries across the owner's endpoints (status only, no bodies)

```text
GET /api/v1/me/deliveries
```

Requires an API key: `Authorization: Bearer upv_live_…`, from your server.

| Parameter | In | | Values | Default |
|---|---|---|---|---|
| `limit` | query | optional | integer 1 to 100 | `50` |

Returns `kind: "deliveries"` with `data` as array of [Delivery](#delivery).

Errors: `400` · `401` · `403` · `429` · `503`.

## Webhooks

- `value.threshold`: Your startup's Upvera Value moved by at least your threshold since the last notification.
- `ping`: Sent when you add an endpoint or press Send test.

Signatures, retries and a verification example are on the [Webhooks](/api/webhooks/) page.

## Schemas

### Error

| Field | Type | Notes |
|---|---|---|
| `v` | `"upvera/api/v1"` |  |
| `error` | object |  |

### Me

| Field | Type | Notes |
|---|---|---|
| `key` | object |  |
| `owner` | object |  |
| `startups` | array of object |  |
| `webhooks` | array of object |  |

### Delivery

| Field | Type | Notes |
|---|---|---|
| `event_id` | string |  |
| `type` | `value.threshold` · `ping` |  |
| `webhook` | object |  |
| `startup` | string or null | Startup slug (value.threshold). |
| `change_pct` | number or null |  |
| `state` | `pending` · `retrying` · `ok` · `dead` · `skipped` |  |
| `attempts` | integer |  |
| `code` | integer or null | Your endpoint's HTTP status. |
| `error` | string or null | timeout · dns · tls · network · redirect · http_status · blocked_address · invalid_url · paused · suspended · failing |
| `ms` | integer or null |  |
| `created_at` | string |  |
| `last_at` | string or null |  |

### WebhookEvent

| Field | Type | Notes |
|---|---|---|
| `v` | `"upvera/webhook/v1"` |  |
| `id` | string | evt_…, stable across retries. |
| `type` | `value.threshold` · `ping` |  |
| `created_at` | string |  |
| `data` | object | value.threshold: startup · value · from · change_pct · direction · threshold_pct · as_of · from_at · rule. ping: webhook. |

### Urls

| Field | Type | Notes |
|---|---|---|
| `page` | string |  |
| `value` | string |  |
| `badge` | string |  |

### StartupRow

| Field | Type | Notes |
|---|---|---|
| `slug` | string |  |
| `name` | string |  |
| `tagline` | string or null |  |
| `category` | string or null |  |
| `rank` | integer |  |
| `value` | number or null | Upvera Value (unitless). |
| `change` | object or null |  |
| `wings` | integer | People with an active wing (count only). |
| `is_new` | boolean |  |
| `urls` | [Urls](#urls) |  |

### Startup

| Field | Type | Notes |
|---|---|---|
| `slug` | string |  |
| `name` | string |  |
| `tagline` | string or null |  |
| `category` | string or null |  |
| `rank` | integer |  |
| `rank_of` | integer |  |
| `value` | number or null |  |
| `changes` | object |  |
| `since_method` | object or null | Change since the current method's first evaluation. |
| `wings` | object or null |  |
| `entered_at` | string or null |  |
| `urls` | [Urls](#urls) |  |

### Series

| Field | Type | Notes |
|---|---|---|
| `slug` | string |  |
| `window` | string |  |
| `value` | number or null |  |
| `points` | array of array of  |  |

### ReceiptData

| Field | Type | Notes |
|---|---|---|
| `slug` | string |  |
| `window` | string |  |
| `receipt` | object or null | null while no receipt exists for the method in force. |

### Index

| Field | Type | Notes |
|---|---|---|
| `name` | `"upvera"` |  |
| `category` | string or null |  |
| `window` | string |  |
| `base` | object |  |
| `members` | integer |  |
| `value` | number or null |  |
| `change_pct` | number or null |  |
| `points` | array of array of  |  |
| `breaks` | array of object | Days where a method change was taken out of the chain. |

---
Source: https://upvera.dev/api/reference/ · Markdown: https://upvera.dev/api/reference.md