# OllyGarden Olive API

> REST API for accessing observability insights and telemetry quality data

Olive provides secure, high-performance programmatic access to OllyGarden's observability platform, designed for MCP servers, CLI tools, and automation clients. It enables seamless integration, automation, and reporting across engineering workflows by exposing instrumentation health metrics and quality insights.

Base URL: https://api.ollygarden.cloud/api/v1
Authentication: Bearer token with API key (format: og_sk_*)
Rate Limit: 60 requests per minute per API key
Response Format: JSON with consistent structure

## Core Endpoints

### Organization
- [GET /api/v1/organization](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1organization/get): Get organization details including subscription tier and instrumentation score

### Services
- [GET /api/v1/services](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1services/get): List all services with instrumentation scores and metadata
- [GET /api/v1/services/grouped](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1services~1grouped/get): List services grouped by name/namespace/environment
- [GET /api/v1/services/search](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1services~1search/get): Search services by name with optional filters
- [GET /api/v1/services/{id}](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1services~1%7Bid%7D/get): Get specific service details including telemetry quality
- [GET /api/v1/services/{id}/versions](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1services~1%7Bid%7D~1versions/get): Get related service versions (same name, different version/env)
- [PATCH /api/v1/services/{id}/favorite](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1services~1%7Bid%7D~1favorite/patch): Set favorite status for a service (per-user, requires JWT auth)
- [GET /api/v1/services/{id}/insights](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1services~1%7Bid%7D~1insights/get): Get insights for a service with pagination

### Insights
- [GET /api/v1/insights](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1insights/get): List all insights with filtering and pagination
- [GET /api/v1/insights/{id}](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1insights~1%7Bid%7D/get): Get specific insight with full details

### Analytics
- [GET /api/v1/analytics/services](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1analytics~1services/get): Get service usage and cost analytics data. Each service in the response includes `versions` (map of version string to service UUID) and `latest_version` (object with `id` and `version` of the most recently seen version) for linking to service details.

### Webhooks
- [GET /api/v1/webhooks](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1webhooks/get): List webhook configurations
- [POST /api/v1/webhooks](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1webhooks/post): Create a webhook configuration
- [GET /api/v1/webhooks/{webhook_id}](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1webhooks~1%7Bwebhook_id%7D/get): Get a webhook configuration
- [PUT /api/v1/webhooks/{webhook_id}](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1webhooks~1%7Bwebhook_id%7D/put): Update a webhook configuration
- [DELETE /api/v1/webhooks/{webhook_id}](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1webhooks~1%7Bwebhook_id%7D/delete): Delete a webhook configuration
- [POST /api/v1/webhooks/{webhook_id}/test](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1webhooks~1%7Bwebhook_id%7D~1test/post): Send a test event to the webhook URL
- [GET /api/v1/webhooks/{webhook_id}/deliveries](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1webhooks~1%7Bwebhook_id%7D~1deliveries/get): List deliveries for a webhook
- [GET /api/v1/webhooks/{webhook_id}/deliveries/{delivery_id}](https://api.ollygarden.cloud/openapi.json#/paths/~1api~1v1~1webhooks~1%7Bwebhook_id%7D~1deliveries~1%7Bdelivery_id%7D/get): Get delivery details

### Rose (Clerk JWT required - API keys are not accepted)
- [POST /api/v1/rose/codebase/review/execute](https://api.ollygarden.cloud/openapi.json#/paths/~1rose~1codebase~1review~1execute/post): Execute codebase review
- [POST /api/v1/rose/codebase/fix/execute](https://api.ollygarden.cloud/openapi.json#/paths/~1rose~1codebase~1fix~1execute/post): Execute codebase fix
- [POST /api/v1/rose/codebase/instrumentation/execute](https://api.ollygarden.cloud/openapi.json#/paths/~1rose~1codebase~1instrumentation~1execute/post): Execute codebase instrumentation
- [GET /api/v1/rose/executions](https://api.ollygarden.cloud/openapi.json#/paths/~1rose~1executions/get): List Rose executions with pagination and filters
- [GET /api/v1/rose/repositories](https://api.ollygarden.cloud/openapi.json#/paths/~1rose~1repositories/get): List Rose repositories with installation metadata, VCS identifiers, and canonical repo URLs
- [GET /api/v1/rose/admin/installations](https://api.ollygarden.cloud/openapi.json#/paths/~1rose~1admin~1installations/get): List GitHub App installations (admin)
- [POST /api/v1/rose/onboarding/session](https://api.ollygarden.cloud/openapi.json#/paths/~1rose~1onboarding~1session/post): Create onboarding session, returns GitHub App installation URL
- [GET /api/v1/rose/onboarding/status](https://api.ollygarden.cloud/openapi.json#/paths/~1rose~1onboarding~1status/get): Get onboarding status including installation state and repo counts
- [POST /api/v1/rose/onboarding/repos](https://api.ollygarden.cloud/openapi.json#/paths/~1rose~1onboarding~1repos/post): Select repos to activate, completes onboarding

## Authentication

All API requests require a Bearer token in the Authorization header:

```
Authorization: Bearer og_sk_your_api_key_here
```

API keys are:
- Scoped to organizations for data isolation
- Read-only for security
- Rate limited to prevent abuse
- Revocable through the OllyGarden dashboard

## Response Format

List endpoints return a top-level `data` array. For example, `GET /api/v1/services` responds with:
```json
{
  "data": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "organization_id": "org_demo",
      "name": "demo-service",
      "version": "1.2.3",
      "environment": "production",
      "is_favorite": false,
      "first_seen_at": "2024-09-01T12:00:00Z",
      "last_seen_at": "2024-09-15T12:00:00Z",
      "created_at": "2024-09-01T12:00:00Z",
      "updated_at": "2024-09-15T12:00:00Z"
    }
  ]
}
```

Detail endpoints return a single object in `data` with metadata and hyperlinks when available. Example `GET /api/v1/services/{id}`:
```json
{
  "data": {
    "id": "11111111-2222-3333-4444-555555555555",
    "organization_id": "org_demo",
    "name": "demo-service",
    "version": "1.2.3",
    "environment": "production",
    "is_favorite": false,
    "first_seen_at": "2024-09-01T12:00:00Z",
    "last_seen_at": "2024-09-15T12:00:00Z",
    "created_at": "2024-09-01T12:00:00Z",
    "updated_at": "2024-09-15T12:00:00Z"
  },
  "meta": {
    "timestamp": "2024-09-20T09:30:00Z"
  },
  "links": {
    "insights": "/api/v1/services/11111111-2222-3333-4444-555555555555/insights"
  }
}
```

`GET /api/v1/insights` and `GET /api/v1/services/{id}/insights` include aggregation metadata. When fetched via `/api/v1/insights`, service info is included:
```json
{
  "data": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "service_id": "11111111-2222-3333-4444-555555555555",
      "service_name": "demo-service",
      "service_version": "1.2.3",
      "service_environment": "production",
      "service_namespace": "default",
      "status": "active",
      "attributes": {
        "signal_type": "TRACES",
        "span_name": "GET /demo/orders",
        "suspicious_attributes": "[\"demo_token\"]"
      },
      "trace_id": "0123456789abcdef0123456789abcdef",
      "telemetry_ts": "2024-09-10T08:00:00Z",
      "detected_ts": "2024-09-12T08:00:00Z",
      "created_at": "2024-09-12T08:00:00Z",
      "updated_at": "2024-09-12T08:00:00Z",
      "insight_type": {
        "id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
        "name": "demo_insight",
        "display_name": "Demo Insight",
        "impact": "Critical"
      }
    }
  ],
  "meta": {
    "timestamp": "2024-09-12T08:05:00Z",
    "total": 1
  }
}
```

Error responses (4xx/5xx) use the following structure:
```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {
      "provided_key_prefix": "og_sk_"
    }
  },
  "meta": {
    "timestamp": "2024-09-20T09:30:00Z"
  }
}
```

## Query Parameters

Pagination (all list endpoints):
- `limit`: Results per page (default: 50, max: 100)
- `offset`: Number of results to skip (default: 0)

Service search (`/services/search`):
- `q`: Search query (required)
- `environment`: Filter by environment
- `namespace`: Filter by namespace

Grouped services (`/services/grouped`):
- `sort`: Sort order (default: insights-first)
  - `insights-first`: Services with insights first, then by insight count descending, then by name
  - `name-asc`: Alphabetical A-Z
  - `name-desc`: Alphabetical Z-A
  - `created-asc`: Oldest first
  - `created-desc`: Newest first

Insights filtering (`/insights`):
- `status`: Filter by status (active, archived, muted)
- `signal_type`: Filter by signal type (trace, metric, log)
- `impact`: Filter by impact level (Critical, Important, Medium, Low)
- `service_id`: Filter by service UUID
- `date_from`: Filter by creation date (RFC3339)
- `date_to`: Filter by creation date (RFC3339)
- `sort`: Sort field with direction prefix (+/- for asc/desc, default: -created_at)

## Error Codes

- `400 Bad Request`: Invalid request parameters
- `401 Unauthorized`: Invalid or missing API key
- `404 Not Found`: Resource not found
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: Server error, retry with backoff

## Data Models

Organization:
- `tier`: Subscription tier details
  - `name`: Tier name (free, startup, enterprise)
  - `features`: List of enabled features
  - `allowed_insight_types`: Restricted insight types for free tier (null for paid tiers)
- `score`: Organization instrumentation score (null if not calculated)
  - `value`: Overall score (0-100)
  - `updated_at`: When score was last calculated

Service:
- `id`: UUID of the service
- `organization_id`: UUID of the owning organization
- `name`: Service name
- `version`: Service version
- `environment`: Deployment environment
- `is_favorite`: Whether this service is marked as a favorite by the current user (boolean, per-user via JWT)
- `instrumentation_score`: Instrumentation summary object (present only when a score has been calculated)
- `created_at`: ISO 8601 timestamp
- `updated_at`: ISO 8601 timestamp

GroupedService (from `/services/grouped`):
- `name`: Service name
- `namespace`: Service namespace
- `environment`: Deployment environment
- `version_count`: Number of different versions for this service group
- `latest_id`: UUID of the most recently seen service version
- `insights_count`: Number of active insights for the most recent version
- `is_favorite`: Whether any version in this service group is marked as a favorite by the current user (boolean, per-user via JWT)
- `instrumentation_score`: Instrumentation summary object for the most recent version (optional)

Insight:
- `id`: UUID of the insight
- `service_id`: UUID of the related service
- `service_name`: Name of the related service (included in list responses)
- `service_version`: Version of the related service (included in list responses)
- `service_environment`: Environment of the related service (included in list responses)
- `service_namespace`: Namespace of the related service (included in list responses)
- `status`: Current state (active, archived, muted)
- `attributes`: Dynamic object containing insight-specific data
- `trace_id`: OpenTelemetry trace ID (if applicable)
- `telemetry_ts`: Timestamp from telemetry data
- `detected_ts`: When the insight was detected
- `created_at`: When the insight record was created
- `updated_at`: When the insight was last updated
- `insight_type`: Insight type details including name, display_name, impact, and remediation_instructions

WebhookConfig:
- `id`: UUID of the webhook configuration
- `organization_id`: UUID of the owning organization
- `name`: Human-readable name (max 255 chars)
- `url`: HTTPS URL to deliver events to
- `event_types`: Insight type IDs to subscribe to (empty = all)
- `environments`: Environments to subscribe to (empty = all)
- `min_severity`: Minimum severity level (Low, Normal, Important, Critical)
- `is_enabled`: Whether the webhook is enabled
- `created_at`: ISO 8601 timestamp
- `updated_at`: ISO 8601 timestamp

WebhookDelivery:
- `id`: UUID of the delivery
- `webhook_config_id`: UUID of the webhook configuration
- `insight_id`: UUID of the insight that triggered the delivery
- `organization_id`: UUID of the owning organization
- `status`: Delivery status (pending, success, failed, exhausted)
- `attempt_number`: Number of delivery attempts made
- `http_status_code`: HTTP status code returned (if available)
- `error_message`: Error message (if failed)
- `idempotency_key`: Idempotency key for deduplication
- `created_at`: ISO 8601 timestamp
- `completed_at`: ISO 8601 timestamp (if completed)

## Optional

- [OpenAPI Specification](/openapi.json): Complete API specification in OpenAPI 3.0 format
- [GitHub Repository](https://github.com/ollygarden/olive): Source code and issue tracking