GitHub

Service Catalog API Reference

Service catalog maps services to ownership, tier, and operational context.

Base URL: http://localhost:3003

Auth + Permissions

  • incidents:view for reads.
  • team:manage for upsert/manage.

GET /services/catalog

List service ownership entries for the current organization.

Response

[
  {
    "id": "s0000000-0000-4000-8000-000000000001",
    "organizationId": "org_123",
    "serviceName": "payment-service",
    "ownerMemberId": "member_123",
    "ownerTeam": "payments-platform",
    "tier": "tier-1",
    "sloTargetMinutes": 30,
    "errorBudgetRemainingPct": 18,
    "repoUrl": "https://github.com/acme/payment-service",
    "dashboardUrl": "https://grafana.acme.io/d/payment-service",
    "escalationPolicy": "pagerduty:payments-primary",
    "createdAt": "2026-04-13T10:00:00.000Z",
    "updatedAt": "2026-04-13T10:00:00.000Z"
  }
]

GET /services/catalog/governance/report?staleAfterDays=30

Get service catalog governance findings for ownership, escalation coverage, stale metadata, and dependency graph gaps.

Query Parameters

ParameterTypeDefaultDescription
staleAfterDaysnumber30Mark catalog entry stale when updatedAt is older than this many days

Response

{
  "generatedAt": "2026-04-25T00:00:00.000Z",
  "staleAfterDays": 30,
  "totalServices": 12,
  "ownedServices": 10,
  "unownedServices": 2,
  "staleServices": 3,
  "unknownDependencyCount": 1,
  "findings": [
    {
      "serviceName": "payment-service",
      "severity": "critical",
      "code": "missing-owner",
      "message": "payment-service has no owner member or owner team."
    },
    {
      "serviceName": "checkout-api",
      "severity": "warning",
      "code": "unknown-dependency",
      "message": "checkout-api depends on unmapped service feature-flag-service."
    }
  ]
}

Finding codes:

  • missing-owner: no ownerMemberId or ownerTeam
  • missing-escalation-policy: tier-1 / tier-2 service lacks escalation policy
  • stale-catalog-entry: metadata older than staleAfterDays
  • unknown-dependency: service depends on unmapped upstream service
  • unknown-dependent: dependency link exists for service with no catalog entry

PUT /services/catalog/:serviceName

Create or update service ownership metadata for a service.

Path Params

ParameterTypeDescription
serviceNamestringService key/name (org-scoped unique)

Body

{
  "ownerMemberId": "member_123",
  "ownerTeam": "payments-platform",
  "tier": "tier-1",
  "sloTargetMinutes": 30,
  "errorBudgetRemainingPct": 18,
  "repoUrl": "https://github.com/acme/payment-service",
  "dashboardUrl": "https://grafana.acme.io/d/payment-service",
  "escalationPolicy": "pagerduty:payments-primary"
}

PUT /services/catalog/:serviceName/dependencies

Replace direct dependency list for one service. Existing links for this service are fully replaced.

Validation + normalization rules:

  • dependsOnServices must be an array of strings (400 otherwise).
  • Values are trimmed.
  • Empty values are dropped.
  • Duplicate values are deduplicated.
  • Self-reference (serviceName depends on itself) is ignored.

Body

{
  "dependsOnServices": ["postgres-primary", "redis-cache", "feature-flag-service"]
}

Invalid Body Example (400 Bad Request)

{
  "dependsOnServices": ["postgres-primary", 123]
}

Response

{
  "serviceName": "payment-service",
  "dependsOnServices": ["postgres-primary", "redis-cache", "feature-flag-service"]
}

GET /services/catalog/:serviceName/graph

Get org-scoped ownership graph for one service.

Response

{
  "serviceName": "payment-service",
  "service": {
    "id": "s0000000-0000-4000-8000-000000000001",
    "serviceName": "payment-service",
    "ownerMemberId": "member_123",
    "ownerTeam": "payments-platform",
    "tier": "tier-1",
    "sloTargetMinutes": 30,
    "errorBudgetRemainingPct": 18,
    "repoUrl": "https://github.com/acme/payment-service",
    "dashboardUrl": "https://grafana.acme.io/d/payment-service",
    "escalationPolicy": "pagerduty:payments-primary",
    "updatedAt": "2026-04-13T10:05:00.000Z"
  },
  "upstream": [
    {
      "id": "s0000000-0000-4000-8000-000000000002",
      "serviceName": "postgres-primary",
      "ownerMemberId": null,
      "ownerTeam": "database",
      "tier": "tier-1",
      "sloTargetMinutes": 15,
      "errorBudgetRemainingPct": 9,
      "repoUrl": null,
      "dashboardUrl": null,
      "escalationPolicy": "pagerduty:db-primary",
      "updatedAt": "2026-04-13T10:05:00.000Z"
    }
  ],
  "downstream": [],
  "unknownUpstream": ["feature-flag-service"],
  "unknownDownstream": []
}

Response

{
  "id": "s0000000-0000-4000-8000-000000000001",
  "organizationId": "org_123",
  "serviceName": "payment-service",
  "ownerMemberId": "member_123",
  "ownerTeam": "payments-platform",
  "tier": "tier-1",
  "sloTargetMinutes": 30,
  "errorBudgetRemainingPct": 18,
  "repoUrl": "https://github.com/acme/payment-service",
  "dashboardUrl": "https://grafana.acme.io/d/payment-service",
  "escalationPolicy": "pagerduty:payments-primary",
  "createdAt": "2026-04-13T10:00:00.000Z",
  "updatedAt": "2026-04-13T10:05:00.000Z"
}