v1 API surface (stable)
The OwlViz public HTTP API is versioned by path prefix **/v1**. This sprint **does not rename** existing routes. The official SDK (@owlviz/sdk) binds directly to these paths.
Base URL: https://api.owlviz.dev
Source of truth: [OpenAPI 3.1](https://api.owlviz.dev/openapi.json) (apps/api/src/openapi/public-api.json in the monorepo).
Response envelope
Successful reads typically return:
json
{ "data": { } }Paginated lists may add pagination.nextCursor. Errors: { "error": { "code", "message" } }.
Assets
| Method | Path | SDK |
|---|---|---|
| GET | /v1/assets/:mint | client.assets.get(mint) |
| GET | /v1/assets/:mint/health | — (use OpenAPI / fetch) |
| GET | /v1/assets/:mint/inspection | — |
| GET | /v1/assets/:mint/media | — |
| GET | /v1/assets/:mint/snapshots | — |
Collections
| Method | Path | SDK |
|---|---|---|
| GET | /v1/collections/:address | client.collections.get(address) |
| GET | /v1/collections/:address/health | — |
| GET | /v1/collections/:address/holders | client.collections.holders(address) |
| GET | /v1/collections/:address/assets | — |
Market (under collections)
| Method | Path | SDK |
|---|---|---|
| GET | /v1/collections/:address/market | client.market.get(address) |
| GET | /v1/collections/:address/market/reference | client.market.reference(address) |
| GET | /v1/collections/:address/market/history | client.market.history(address) |
| GET | /v1/collections/:address/market/state | — |
| GET | /v1/collections/:address/market/events | client.market.events(address) |
| GET | /v1/collections/:address/market-watch | — |
Global market automation
| Method | Path | SDK |
|---|---|---|
| GET | /v1/market-events | client.market.listEvents() |
| GET | /v1/market-events/:id | — |
| POST/PATCH/DELETE | /v1/market-watches | — (keyed; portal or fetch) |
Change monitors (SDK read surface)
| Method | Path | SDK |
|---|---|---|
| GET | /v1/monitors | client.monitors.list() |
| GET | /v1/monitors/:id | client.monitors.get(id) |
| POST/PATCH/DELETE | /v1/monitors | — (see [monitoring.md](./monitoring.md)) |
Webhooks & monitor events
| Method | Path |
|---|---|
| GET/POST/PATCH/DELETE | /v1/webhooks, /v1/webhooks/:id, … |
| GET | /v1/events (monitor event feed, keyed) |
See [webhooks.md](./webhooks.md) and [monitoring.md](./monitoring.md).
Auth
Authorization: Bearer ov_live_… on keyed routes. Documented in [authentication.md](./authentication.md).