---
title: Discovery
description: Discovery protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Service Status Enum

Describes the operational state of a service in the discovery response.

- `available`   – Fully operational: service is registered AND HTTP handler is verified.

- `registered`  – Route is declared in the dispatcher table but the HTTP handler has

not been verified (may 501 at runtime).

- `unavailable` – Service is not installed / not registered in the kernel.

- `degraded`    – Partially working (e.g., in-memory fallback, missing persistence).

- `stub`        – Placeholder handler that always returns 501 Not Implemented.

<Callout type="info">
**Source:** `packages/spec/src/api/discovery.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { ApiRoutes, Discovery, RouteHealthEntry, RouteHealthReport, ServiceInfo, WellKnownCapabilities } from '@objectstack/spec/api';
import type { ApiRoutes, Discovery, RouteHealthEntry, RouteHealthReport, ServiceInfo, WellKnownCapabilities } from '@objectstack/spec/api';

// Validate data
const result = ApiRoutes.parse(data);
```

---

## ApiRoutes

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **data** | `string` | ✅ | e.g. /api/v1/data |
| **metadata** | `string` | ✅ | e.g. /api/v1/meta |
| **discovery** | `string` | optional | e.g. /api/v1/discovery |
| **ui** | `string` | optional | e.g. /api/v1/ui |
| **auth** | `string` | optional | e.g. /api/v1/auth |
| **automation** | `string` | optional | e.g. /api/v1/automation |
| **storage** | `string` | optional | e.g. /api/v1/storage |
| **analytics** | `string` | optional | e.g. /api/v1/analytics |
| **graphql** | `string` | optional | e.g. /graphql |
| **packages** | `string` | optional | e.g. /api/v1/packages |
| **workflow** | `string` | optional | e.g. /api/v1/workflow |
| **approvals** | `string` | optional | e.g. /api/v1/approvals |
| **realtime** | `string` | optional | e.g. /api/v1/realtime |
| **notifications** | `string` | optional | e.g. /api/v1/notifications |
| **ai** | `string` | optional | e.g. /api/v1/ai |
| **i18n** | `string` | optional | e.g. /api/v1/i18n |
| **feed** | `string` | optional | e.g. /api/v1/feed |


---

## Discovery

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ |  |
| **version** | `string` | ✅ |  |
| **environment** | `Enum<'production' \| 'sandbox' \| 'development'>` | ✅ |  |
| **routes** | `Object` | ✅ |  |
| **locale** | `Object` | ✅ |  |
| **services** | `Record<string, Object>` | ✅ | Per-service availability map keyed by CoreServiceName |
| **capabilities** | `Record<string, Object>` | optional | Hierarchical capability descriptors for frontend intelligent adaptation |
| **schemaDiscovery** | `Object` | optional | Schema discovery endpoints for API toolchain integration |
| **metadata** | `Record<string, any>` | optional | Custom metadata key-value pairs for extensibility |


---

## RouteHealthEntry

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **route** | `string` | ✅ | Route path pattern |
| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP method (GET, POST, etc.) |
| **service** | `string` | ✅ | Target service name |
| **declared** | `boolean` | ✅ | Whether the route is declared in discovery/metadata |
| **handlerRegistered** | `boolean` | ✅ | Whether the HTTP handler is registered |
| **healthStatus** | `Enum<'pass' \| 'fail' \| 'missing' \| 'skip'>` | ✅ | pass = handler responds, fail = 501/503, missing = no handler (404), skip = not checked |
| **message** | `string` | optional | Diagnostic message |


---

## RouteHealthReport

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **timestamp** | `string` | ✅ | ISO 8601 timestamp of report generation |
| **adapter** | `string` | ✅ | Adapter or runtime that produced this report |
| **totalDeclared** | `integer` | ✅ | Total routes declared in discovery |
| **totalRegistered** | `integer` | ✅ | Routes with confirmed handler |
| **totalMissing** | `integer` | ✅ | Routes missing a handler |
| **routes** | `Object[]` | ✅ | Per-route health entries |


---

## ServiceInfo

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ |  |
| **status** | `Enum<'available' \| 'registered' \| 'unavailable' \| 'degraded' \| 'stub'>` | ✅ | available = fully operational, registered = route declared but handler unverified, unavailable = not installed, degraded = partial, stub = placeholder that returns 501 |
| **handlerReady** | `boolean` | optional | Whether the HTTP handler is confirmed to be mounted. Omitted = readiness unknown/unverified; true = handler mounted; false = handler missing or stub (likely 501). |
| **route** | `string` | optional | e.g. /api/v1/analytics |
| **provider** | `string` | optional | e.g. "objectql", "plugin-redis", "driver-memory" |
| **version** | `string` | optional | Semantic version of the service implementation (e.g. "3.0.6") |
| **message** | `string` | optional | e.g. "Install plugin-workflow to enable" |
| **rateLimit** | `Object` | optional | Rate limit and quota info for this service |


---

## WellKnownCapabilities

Well-known capability flags for frontend intelligent adaptation

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **feed** | `boolean` | ✅ | Whether the backend supports Feed / Chatter API |
| **comments** | `boolean` | ✅ | Whether the backend supports comments (a subset of Feed) |
| **automation** | `boolean` | ✅ | Whether the backend supports Automation CRUD (flows, triggers) |
| **cron** | `boolean` | ✅ | Whether the backend supports cron scheduling |
| **search** | `boolean` | ✅ | Whether the backend supports full-text search |
| **export** | `boolean` | ✅ | Whether the backend supports async export |
| **chunkedUpload** | `boolean` | ✅ | Whether the backend supports chunked (multipart) uploads |


---

