Declare a service · Catalog API

POST/api/v1/catalog/components

Declares a service. slug and display_name are required. kind defaults to service and lifecycle to production. The slug is a DNS label (lowercase letters, digits and single hyphens, starting with a letter, at most 63 characters) and can never change.

Resources already running whose evohub.io/component annotation names the new slug are matched to it straight away.

Requires the catalog:component:write scope.

Authorization

Any one of:

Request body required

Content type: application/json

Type: CreateComponentRequest

slug string required
Max length: 63 · Pattern: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$
display_name string required
Max length: 100
description string
Max length: 2000
kind ComponentKind
One of: service library database website job other
owner_team_id string | null
A team ID (team_…), or null for no owner.
tier_id string | null
One of the organization's tiers in use.
tier integer | null
Instead of tier_id, the tier at this place in the order.
sla_overrides SLATargets
Show SLATargets properties
- availability number
  A percentage above 0 and at most 100, up to 3 decimals.
  Example: 99.9
- response object
  Minutes to acknowledge, per On-Call severity (critical, high, medium, low, info), 1 to 525600.
  Other keys: integer
- resolution object
  Minutes to resolve, per severity.
  Other keys: integer
- support_hours object
  - kind string required
    One of: 24x7 business
  - timezone string
    Example: Europe/Istanbul
  - days array of integer
    ISO weekdays, 1 is Monday.
  - from string
    Example: 09:00
  - to string
    Example: 18:00
- max_unowned_days integer
  Minimum: 0 · Maximum: 3650
lifecycle Lifecycle
One of: experimental production deprecated retired
repo_url string
Empty, or an http(s) URL with a host and no user name or password, at most 2048 characters. The same for docs_url and runbook_url.
docs_url string
runbook_url string

Responses

`201`

The service.

Content type: application/json

Type: ComponentEnvelope

data Component
Show Component properties
- id string
  Example: cmp_7a1d3f5b9c2e4a6b8d0f1e3c5a7b9d2f
- org_id string
- slug string
  Example: payments-api
- display_name string
  Example: Payments API
- description string
- kind ComponentKind
  One of: service library database website job other
- owner_team_id string | null
- tier_id string | null
- tier integer | null
  The tier's place in the order, 1 the most critical.
- sla_overrides SLATargets
  Show SLATargets properties
  - availability number
    A percentage above 0 and at most 100, up to 3 decimals.
    Example: 99.9
  - response object
    Minutes to acknowledge, per On-Call severity (critical, high, medium, low, info), 1 to 525600.
    Other keys: integer
  - resolution object
    Minutes to resolve, per severity.
    Other keys: integer
  - support_hours object
    kind string required
    One of: 24x7 business
    timezone string
    Example: Europe/Istanbul
    days array of integer
    ISO weekdays, 1 is Monday.
    from string
    Example: 09:00
    to string
    Example: 18:00
  - max_unowned_days integer
    Minimum: 0 · Maximum: 3650
- lifecycle Lifecycle
  One of: experimental production deprecated retired
- repo_url string
- docs_url string
- runbook_url string
- created_by string
- created_at string (date-time)
- updated_at string (date-time)

`400`

The request is not valid: a field or filter value is wrong (VALIDATION_ERROR, with a sentence saying what), the body is not the expected JSON or carries an unknown field (INVALID_BODY), the cursor is not one this list gave (INVALID_CURSOR), a binding names a service that does not exist (UNKNOWN_COMPONENT), or a PATCH tries to change a slug (SLUG_IMMUTABLE).

Content type: application/json

Type: Error

error object required
- code string required
  Example: NOT_FOUND
- message string required
  Example: not found
- request_id string

`401`

No API key was sent, or it is unknown, revoked or expired (UNAUTHORIZED).

Content type: application/json

Type: Error

error object required
- code string required
  Example: NOT_FOUND
- message string required
  Example: not found
- request_id string

`403`

The key lacks a scope this endpoint needs (FORBIDDEN).

Content type: application/json

Type: Error

error object required
- code string required
  Example: NOT_FOUND
- message string required
  Example: not found
- request_id string

`409`

A service with this slug exists (SLUG_TAKEN), or the tier is archived (TIER_ARCHIVED).

Content type: application/json

Type: Error

error object required
- code string required
  Example: NOT_FOUND
- message string required
  Example: not found
- request_id string

`429`

Too many requests (RATE_LIMITED). Wait for Retry-After seconds.

Headers

Retry-After integer
Seconds to wait before retrying.

Content type: application/json

Type: Error

error object required
- code string required
  Example: NOT_FOUND
- message string required
  Example: not found
- request_id string

`500`

Something went wrong on EvoHub's side (INTERNAL_ERROR). Retry later.

Content type: application/json

Type: Error

error object required
- code string required
  Example: NOT_FOUND
- message string required
  Example: not found
- request_id string

Example request

curl -X POST 'https://evohub.io/api/v1/catalog/components' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "slug": "payments-api",
  "tier": 1,
  "description": "Takes card payments for checkout.",
  "runbook_url": "https://wiki.acme.example/runbooks/payments",
  "display_name": "Payments API",
  "owner_team_id": "team_3b6f0e2a-1c4d-4e8f-9a7b-2d5c6e8f0a1b"
}'