> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrubbe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Service Map API: Model and Query Service Dependencies

> Register services, declare upstream and downstream dependencies, and query topology data to understand blast radius and cascading failure risks.

The service map API gives you a programmatic interface to the dependency graph that underlies your infrastructure. By registering services and their relationships, you enable the platform to calculate blast radius when an incident occurs, surface downstream impact for any given service, and render an accurate topology view for your team. Changes made through the API are reflected in the visual service map immediately.

All requests require a Bearer token in the `Authorization` header.

***

## Get full topology

`GET https://your-api-domain.com/api/v1/service-map/topology`

Returns the entire service dependency graph as a list of nodes and directed edges. Useful for rendering a complete topology visualization.

### Response fields

<ResponseField name="nodes" type="object[]" required>
  All registered services.

  <Expandable title="node properties">
    <ResponseField name="id" type="string" required>
      Unique service identifier.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Human-readable service name.
    </ResponseField>

    <ResponseField name="team" type="string">
      Owning team slug.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="edges" type="object[]" required>
  Directed dependency relationships between services.

  <Expandable title="edge properties">
    <ResponseField name="id" type="string" required>
      Unique identifier for the dependency.
    </ResponseField>

    <ResponseField name="sourceId" type="string" required>
      ID of the upstream (depended-upon) service.
    </ResponseField>

    <ResponseField name="targetId" type="string" required>
      ID of the downstream (dependent) service.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://your-api-domain.com/api/v1/service-map/topology \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://your-api-domain.com/api/v1/service-map/topology',
    {
      headers: { Authorization: 'Bearer YOUR_TOKEN' },
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://your-api-domain.com/api/v1/service-map/topology',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
  )
  data = response.json()
  ```
</CodeGroup>

***

## List all services

`GET https://your-api-domain.com/api/v1/service-map`

Returns a flat list of all registered services without edge data.

### Response fields

<ResponseField name="services" type="object[]" required>
  Array of service objects.

  <Expandable title="service properties">
    <ResponseField name="id" type="string" required>
      Unique service identifier.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Service name.
    </ResponseField>

    <ResponseField name="description" type="string">
      Optional description of the service's purpose.
    </ResponseField>

    <ResponseField name="team" type="string">
      Owning team slug.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp of the last modification.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://your-api-domain.com/api/v1/service-map \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://your-api-domain.com/api/v1/service-map',
    {
      headers: { Authorization: 'Bearer YOUR_TOKEN' },
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://your-api-domain.com/api/v1/service-map',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
  )
  data = response.json()
  ```
</CodeGroup>

***

## Get a service

`GET https://your-api-domain.com/api/v1/service-map/:id`

Retrieves the full record for a single service.

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the service.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://your-api-domain.com/api/v1/service-map/svc_payments \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://your-api-domain.com/api/v1/service-map/svc_payments',
    {
      headers: { Authorization: 'Bearer YOUR_TOKEN' },
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://your-api-domain.com/api/v1/service-map/svc_payments',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
  )
  data = response.json()
  ```
</CodeGroup>

***

## Get downstream impact

`GET https://your-api-domain.com/api/v1/service-map/:id/downstream-impact`

Returns all services that directly or transitively depend on the specified service. Use this before making changes to understand blast radius.

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the upstream service to analyze.
</ParamField>

### Response fields

<ResponseField name="impactedServices" type="object[]" required>
  Services that would be affected if the target service degrades or goes offline.

  <Expandable title="impacted service properties">
    <ResponseField name="id" type="string" required>
      Service identifier.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Service name.
    </ResponseField>

    <ResponseField name="depth" type="number" required>
      Number of dependency hops from the target service. `1` means directly dependent.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://your-api-domain.com/api/v1/service-map/svc_payments/downstream-impact \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://your-api-domain.com/api/v1/service-map/svc_payments/downstream-impact',
    {
      headers: { Authorization: 'Bearer YOUR_TOKEN' },
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://your-api-domain.com/api/v1/service-map/svc_payments/downstream-impact',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
  )
  data = response.json()
  ```
</CodeGroup>

***

## Create a service

`POST https://your-api-domain.com/api/v1/service-map`

Registers a new service in the service map. After creation, add dependencies with [POST /dependencies](#add-a-dependency).

### Request body

<ParamField body="name" type="string" required placeholder="Payment Service">
  A unique, human-readable name for the service.
</ParamField>

<ParamField body="description" type="string" placeholder="Handles all payment processing and fraud checks.">
  A short description of the service's role.
</ParamField>

<ParamField body="team" type="string" placeholder="payments-team">
  The team slug responsible for this service.
</ParamField>

### Response fields

<ResponseField name="id" type="string" required>
  Server-assigned unique identifier for the new service.
</ResponseField>

<ResponseField name="name" type="string" required>
  The service name.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 creation timestamp.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://your-api-domain.com/api/v1/service-map \
    --header 'Authorization: Bearer YOUR_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Payment Service",
      "description": "Handles all payment processing and fraud checks.",
      "team": "payments-team"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://your-api-domain.com/api/v1/service-map',
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        name: 'Payment Service',
        description: 'Handles all payment processing and fraud checks.',
        team: 'payments-team',
      }),
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://your-api-domain.com/api/v1/service-map',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
      json={
          'name': 'Payment Service',
          'description': 'Handles all payment processing and fraud checks.',
          'team': 'payments-team',
      },
  )
  data = response.json()
  ```
</CodeGroup>

***

## Add a dependency

`POST https://your-api-domain.com/api/v1/service-map/dependencies`

Declares a dependency relationship between two registered services. The `sourceId` service depends on the `targetId` service.

### Request body

<ParamField body="sourceId" type="string" required>
  The ID of the downstream (dependent) service.
</ParamField>

<ParamField body="targetId" type="string" required>
  The ID of the upstream (depended-upon) service.
</ParamField>

### Response fields

<ResponseField name="id" type="string" required>
  Unique identifier for the new dependency record.
</ResponseField>

<ResponseField name="sourceId" type="string" required>
  The dependent service ID.
</ResponseField>

<ResponseField name="targetId" type="string" required>
  The upstream service ID.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://your-api-domain.com/api/v1/service-map/dependencies \
    --header 'Authorization: Bearer YOUR_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
      "sourceId": "svc_checkout",
      "targetId": "svc_payments"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://your-api-domain.com/api/v1/service-map/dependencies',
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        sourceId: 'svc_checkout',
        targetId: 'svc_payments',
      }),
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://your-api-domain.com/api/v1/service-map/dependencies',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
      json={
          'sourceId': 'svc_checkout',
          'targetId': 'svc_payments',
      },
  )
  data = response.json()
  ```
</CodeGroup>

***

## Update a service

`PATCH https://your-api-domain.com/api/v1/service-map/:id`

Partially updates a service record. Only fields included in the request body are modified.

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the service to update.
</ParamField>

### Request body

<ParamField body="name" type="string">
  New name for the service.
</ParamField>

<ParamField body="description" type="string">
  Updated description.
</ParamField>

<ParamField body="team" type="string">
  Updated owning team slug.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://your-api-domain.com/api/v1/service-map/svc_payments \
    --header 'Authorization: Bearer YOUR_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
      "description": "Handles payments, fraud checks, and refund processing."
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://your-api-domain.com/api/v1/service-map/svc_payments',
    {
      method: 'PATCH',
      headers: {
        Authorization: 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        description: 'Handles payments, fraud checks, and refund processing.',
      }),
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      'https://your-api-domain.com/api/v1/service-map/svc_payments',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
      json={'description': 'Handles payments, fraud checks, and refund processing.'},
  )
  data = response.json()
  ```
</CodeGroup>

***

## Delete a service

`DELETE https://your-api-domain.com/api/v1/service-map/:id`

Removes a service and all of its dependency relationships from the service map.

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the service to delete.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://your-api-domain.com/api/v1/service-map/svc_payments \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://your-api-domain.com/api/v1/service-map/svc_payments',
    {
      method: 'DELETE',
      headers: { Authorization: 'Bearer YOUR_TOKEN' },
    }
  );
  ```

  ```python Python theme={null}
  import requests

  requests.delete(
      'https://your-api-domain.com/api/v1/service-map/svc_payments',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
  )
  ```
</CodeGroup>

***

## Delete a dependency

`DELETE https://your-api-domain.com/api/v1/service-map/dependencies/:depId`

Removes a single dependency relationship. The services themselves are not affected.

### Path parameters

<ParamField path="depId" type="string" required>
  The unique identifier of the dependency to remove.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://your-api-domain.com/api/v1/service-map/dependencies/dep_abc123 \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://your-api-domain.com/api/v1/service-map/dependencies/dep_abc123',
    {
      method: 'DELETE',
      headers: { Authorization: 'Bearer YOUR_TOKEN' },
    }
  );
  ```

  ```python Python theme={null}
  import requests

  requests.delete(
      'https://your-api-domain.com/api/v1/service-map/dependencies/dep_abc123',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
  )
  ```
</CodeGroup>