API Reference

Shoehorn Admin API

v1.0.0

Administrative endpoints for tenant settings, API keys, policies, features, scorecards, role bundles, database management, and system info.

Base URL: https://shoehorn.example.com/api/v1

/

Settings

GET /admin/settings #

Get tenant settings

Responses

200 Current tenant settings

curl -X GET 'https://shoehorn.example.com/api/v1/admin/settings' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/settings', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/settings',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/settings", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /admin/settings #

Update tenant settings

Request body required

Content-Type: application/json

Free-form JSON object (no fixed schema).

Responses

200 Settings updated

curl -X PUT 'https://shoehorn.example.com/api/v1/admin/settings' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/settings', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/admin/settings',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/admin/settings", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

API Keys

GET /admin/api-keys #

List API keys

Responses

200 API keys (tokens are masked)

Schema (application/json)

object
1property
keysarray<APIKey>
8properties
idstring<uuid>
namestring
prefixstring
First 8 chars of token (shp_svc_)
scopesarray<string>
last_usedstring<date-time>
expires_atstring<date-time>
created_atstring<date-time>
revokedboolean

curl -X GET 'https://shoehorn.example.com/api/v1/admin/api-keys' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/api-keys', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/api-keys',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/api-keys", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /admin/api-keys #

Generate API key

Request body required

Content-Type: application/json

object

3properties

namestring*

scopesarray<string>*

expires_atstring<date-time>

Responses

201 API key generated (token shown only once)

Schema (application/json)

object
4properties
idstring
namestring
tokenstring
Full token (shp_svc_...) - shown only at creation
scopesarray<string>

curl -X POST 'https://shoehorn.example.com/api/v1/admin/api-keys' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/api-keys',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/api-keys", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

POST /admin/api-keys/{id}/revoke #

Revoke API key

Path parameters

idstringrequired

Responses

200 API key revoked

curl -X POST 'https://shoehorn.example.com/api/v1/admin/api-keys/{id}/revoke' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/api-keys/{id}/revoke', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/api-keys/{id}/revoke',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/api-keys/{id}/revoke", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Policies

GET /admin/policies #

List platform policies

Returns pre-seeded platform policies (config-only, not user-created).

Responses

200 Platform policies

curl -X GET 'https://shoehorn.example.com/api/v1/admin/policies' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/policies', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/policies',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/policies", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /admin/policies/{id} #

Update platform policy

Path parameters

idstringrequired

Request body required

Content-Type: application/json

object

2properties

enabledboolean

configobject

Responses

200 Policy updated

curl -X PUT 'https://shoehorn.example.com/api/v1/admin/policies/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/policies/{id}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/admin/policies/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/admin/policies/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Features

GET /admin/features #

List feature flags

Responses

200 All feature flags

curl -X GET 'https://shoehorn.example.com/api/v1/admin/features' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/features', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/features',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/features", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /admin/features #

Create feature flag

Request body required

Content-Type: application/json

object

4properties

keystring*

namestring*

descriptionstring

enabledboolean

Default: false

Responses

201 Feature flag created

curl -X POST 'https://shoehorn.example.com/api/v1/admin/features' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/features', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/features',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/features", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

PUT /admin/features/{key} #

Update feature flag

Path parameters

keystringrequired

Responses

200 Flag updated

curl -X PUT 'https://shoehorn.example.com/api/v1/admin/features/{key}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/features/{key}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/admin/features/{key}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/admin/features/{key}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DELETE /admin/features/{key} #

Delete feature flag

Path parameters

keystringrequired

Responses

204 Flag deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/admin/features/{key}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/features/{key}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/admin/features/{key}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/admin/features/{key}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /admin/features/{key}/tenants/{tenantId} #

Set tenant feature override

Path parameters

keystringrequired
tenantIdstringrequired

Responses

200 Override set

curl -X POST 'https://shoehorn.example.com/api/v1/admin/features/{key}/tenants/{tenantId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/features/{key}/tenants/{tenantId}', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/features/{key}/tenants/{tenantId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/features/{key}/tenants/{tenantId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DELETE /admin/features/{key}/tenants/{tenantId} #

Remove tenant feature override

Path parameters

keystringrequired
tenantIdstringrequired

Responses

204 Override removed

curl -X DELETE 'https://shoehorn.example.com/api/v1/admin/features/{key}/tenants/{tenantId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/features/{key}/tenants/{tenantId}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/admin/features/{key}/tenants/{tenantId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/admin/features/{key}/tenants/{tenantId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Scorecards

GET /admin/scorecards/categories #

List scorecard categories

Responses

200 Scorecard categories

curl -X GET 'https://shoehorn.example.com/api/v1/admin/scorecards/categories' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/scorecards/categories', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/scorecards/categories',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/scorecards/categories", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /admin/scorecards/categories #

Create scorecard category

Request body required

Content-Type: application/json

object

3properties

namestring*

descriptionstring

weightnumber*

Responses

201 Category created

curl -X POST 'https://shoehorn.example.com/api/v1/admin/scorecards/categories' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/scorecards/categories', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/scorecards/categories',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/scorecards/categories", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

PUT /admin/scorecards/categories/{id} #

Update scorecard category

Path parameters

idstringrequired

Responses

200 Category updated

curl -X PUT 'https://shoehorn.example.com/api/v1/admin/scorecards/categories/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/scorecards/categories/{id}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/admin/scorecards/categories/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/admin/scorecards/categories/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DELETE /admin/scorecards/categories/{id} #

Delete scorecard category

Path parameters

idstringrequired

Responses

204 Category deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/admin/scorecards/categories/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/scorecards/categories/{id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/admin/scorecards/categories/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/admin/scorecards/categories/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /admin/scorecards/rules #

List scorecard rules

Responses

200 Global scorecard rules

curl -X GET 'https://shoehorn.example.com/api/v1/admin/scorecards/rules' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/scorecards/rules', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/scorecards/rules',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/scorecards/rules", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /admin/scorecards/rules #

Create scorecard rule

Responses

201 Rule created

curl -X POST 'https://shoehorn.example.com/api/v1/admin/scorecards/rules' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/scorecards/rules', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/scorecards/rules',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/scorecards/rules", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /admin/scorecards/rules/{id} #

Update scorecard rule

Path parameters

idstringrequired

Responses

200 Rule updated

curl -X PUT 'https://shoehorn.example.com/api/v1/admin/scorecards/rules/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/scorecards/rules/{id}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/admin/scorecards/rules/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/admin/scorecards/rules/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DELETE /admin/scorecards/rules/{id} #

Delete scorecard rule

Path parameters

idstringrequired

Responses

204 Rule deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/admin/scorecards/rules/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/scorecards/rules/{id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/admin/scorecards/rules/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/admin/scorecards/rules/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /admin/scorecards/grading #

Get grading configuration

Responses

200 Grading thresholds

curl -X GET 'https://shoehorn.example.com/api/v1/admin/scorecards/grading' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/scorecards/grading', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/scorecards/grading',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/scorecards/grading", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /admin/scorecards/grading #

Update grading configuration

Responses

200 Grading config updated

curl -X PUT 'https://shoehorn.example.com/api/v1/admin/scorecards/grading' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/scorecards/grading', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/admin/scorecards/grading',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/admin/scorecards/grading", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Role Bundles

GET /admin/role-bundles #

List role bundles

Responses

200 All role bundles

curl -X GET 'https://shoehorn.example.com/api/v1/admin/role-bundles' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/role-bundles', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/role-bundles',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/role-bundles", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /admin/role-bundles #

Create role bundle

Responses

201 Bundle created

curl -X POST 'https://shoehorn.example.com/api/v1/admin/role-bundles' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/role-bundles', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/role-bundles',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/role-bundles", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /admin/role-bundles/{bundleId} #

Get role bundle

Path parameters

bundleIdstringrequired

Responses

200 Bundle details

curl -X GET 'https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /admin/role-bundles/{bundleId} #

Update role bundle

Path parameters

bundleIdstringrequired

Responses

200 Bundle updated

curl -X PUT 'https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DELETE /admin/role-bundles/{bundleId} #

Delete role bundle

Path parameters

bundleIdstringrequired

Responses

204 Bundle deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/admin/role-bundles/{bundleId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Roles

GET /roles #

List all roles

Responses

200 Available roles

curl -X GET 'https://shoehorn.example.com/api/v1/roles' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/roles', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/roles',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/roles", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /roles/users/{userId}/roles #

Assign role to user

Path parameters

userIdstringrequired

Responses

201 Role assigned

curl -X POST 'https://shoehorn.example.com/api/v1/roles/users/{userId}/roles' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/roles/users/{userId}/roles', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/roles/users/{userId}/roles',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/roles/users/{userId}/roles", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DELETE /roles/users/{userId}/roles #

Remove role from user

Path parameters

userIdstringrequired

Responses

204 Role removed

curl -X DELETE 'https://shoehorn.example.com/api/v1/roles/users/{userId}/roles' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/roles/users/{userId}/roles', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/roles/users/{userId}/roles',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/roles/users/{userId}/roles", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Database

GET /database/info #

Get database info

Responses

200 Database version, size, connection stats

curl -X GET 'https://shoehorn.example.com/api/v1/database/info' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/database/info', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/database/info',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/database/info", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /database/connections #

Get database connections

Responses

200 Active database connections

curl -X GET 'https://shoehorn.example.com/api/v1/database/connections' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/database/connections', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/database/connections',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/database/connections", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /database/backups #

List database backups

Responses

200 Available backups

curl -X GET 'https://shoehorn.example.com/api/v1/database/backups' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/database/backups', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/database/backups',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/database/backups", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /database/backup #

Create database backup

Responses

201 Backup initiated

curl -X POST 'https://shoehorn.example.com/api/v1/database/backup' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/database/backup', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/database/backup',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/database/backup", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

System

GET /system #

Get system services info

Responses

200 Status of all microservices

curl -X GET 'https://shoehorn.example.com/api/v1/system' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/system', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/system',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/system", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

License

GET /license #

Get license status

Returns the active license for the calling tenant. Beta tenants also get `beta_ends_at`, `beta_grace_ends_at`, and `is_read_only` populated when applicable.

Responses

200 Current license info

Schema (application/json)

LicenseStatus
17properties
editionstring*
"free""beta""standard""airgapped"
typestring
"selfhosted""saas""partner"
clustersinteger
Per-license cluster-limit override (0 = use tier default)
licenseestring
issued_atstring<date-time>
expires_atstring<date-time>nullable
activated_atstring<date-time>nullable
key_prefixstring
resource_limitsobject*
2properties
clustersinteger*
0 = unlimited
nodesinteger*
0 = unlimited
resource_usagearray<object>
4properties
resourcestring
"clusters""nodes"
usedinteger
limitinteger
0 = unlimited
percentinteger
warningsarray<object>
3properties
typestring
"expired""expiring_soon""resource_high""resource_exceeded"
messagestring
levelstring
"warning""error"
is_expiredboolean*
is_validboolean*
has_licenseboolean*
beta_ends_atstring<date-time>nullable
For Beta licenses: when the 6-month free period ends. Floored at 2026-11-10 for legacy Beta licenses so existing customers don't flip read-only the day per-cluster pricing took over.
beta_grace_ends_atstring<date-time>nullable
For Beta licenses: when the 30-day post-end grace expires. Set only after the first license-status read past beta_ends_at has marked the grace start. After this timestamp the auto-disconnect job runs.
is_read_onlyboolean*
True while a Beta tenant is inside the 30-day grace window. UI mutations return 423 BETA_ENDED_READ_ONLY. Catalog reads and agent traffic stay live; license activation also keeps working so the tenant can switch to Standard without restoring writes first.

curl -X GET 'https://shoehorn.example.com/api/v1/license' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/license', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/license',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/license", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /license/activate #

Activate license

Responses

200 License activated

curl -X POST 'https://shoehorn.example.com/api/v1/license/activate' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/license/activate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/license/activate',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/license/activate", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /license/deactivate #

Deactivate license

Responses

200 License deactivated

curl -X POST 'https://shoehorn.example.com/api/v1/license/deactivate' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/license/deactivate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/license/deactivate',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/license/deactivate", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /license/pending-clusters #

List pending cluster registrations

Agents that registered a cluster past the tenant's licensed cluster count park here. Returns an empty array when nothing is pending.

Responses

200 Pending registrations

Schema (application/json)

array<PendingClusterRegistration>
5properties
cluster_idstring*
namestring*
first_attempted_atstring<date-time>*
last_attempted_atstring<date-time>*
attemptsinteger*

curl -X GET 'https://shoehorn.example.com/api/v1/license/pending-clusters' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/license/pending-clusters', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/license/pending-clusters',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/license/pending-clusters", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DELETE /license/pending-clusters/{cluster_id} #

Dismiss a pending cluster registration

Removes the row from the pending list. Bookkeeping only: this does not grant capacity and does not stop the agent. To raise capacity, request a new signed license. To stop the agent from re-parking, remove it from the cluster.

Path parameters

cluster_idstringrequired

Responses

204 Rejected
404 No pending registration for that cluster_id

curl -X DELETE 'https://shoehorn.example.com/api/v1/license/pending-clusters/{cluster_id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/license/pending-clusters/{cluster_id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/license/pending-clusters/{cluster_id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/license/pending-clusters/{cluster_id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Analytics API

v1.0.0

Aggregate statistics across the catalog, search usage, ownership, lifecycle, and language breakdowns.

Base URL: https://shoehorn.example.com/api/v1

/

Statistics

GET /stats #

Get catalog statistics

Responses

200 Aggregate catalog metrics

Schema (application/json)

object
4properties
total_entitiesinteger
by_typeobject
by_lifecycleobject
by_tierobject

curl -X GET 'https://shoehorn.example.com/api/v1/stats' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/stats', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/stats',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/stats", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /stats/entity-types #

Get entity type breakdown

Responses

200 Count by entity type

curl -X GET 'https://shoehorn.example.com/api/v1/stats/entity-types' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/stats/entity-types', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/stats/entity-types',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/stats/entity-types", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /stats/languages #

Get programming language distribution

Responses

200 Language statistics

curl -X GET 'https://shoehorn.example.com/api/v1/stats/languages' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/stats/languages', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/stats/languages',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/stats/languages", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /stats/lifecycle #

Get lifecycle stage distribution

Responses

200 Count by lifecycle stage

curl -X GET 'https://shoehorn.example.com/api/v1/stats/lifecycle' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/stats/lifecycle', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/stats/lifecycle',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/stats/lifecycle", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /stats/teams #

Get team ownership statistics

Responses

200 Entities per team

curl -X GET 'https://shoehorn.example.com/api/v1/stats/teams' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/stats/teams', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/stats/teams',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/stats/teams", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /stats/unowned #

Get unowned entities

Responses

200 Entities without an owner

curl -X GET 'https://shoehorn.example.com/api/v1/stats/unowned' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/stats/unowned', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/stats/unowned',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/stats/unowned", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Search analytics

GET /analytics/search #

Get search analytics

Responses

200 Search usage analytics

curl -X GET 'https://shoehorn.example.com/api/v1/analytics/search' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/analytics/search', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/analytics/search',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/analytics/search", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /analytics/search/{period} #

Get search analytics by period

Path parameters

period"7d" | "30d" | "90d"required

Responses

200 Search analytics for period

curl -X GET 'https://shoehorn.example.com/api/v1/analytics/search/{period}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/analytics/search/{period}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/analytics/search/{period}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/analytics/search/{period}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Authentication API

v1.0.0

Authentication status for CLI and programmatic clients.

Base URL: https://shoehorn.example.com/api/v1

/

Authentication

GET /auth/cli/status #

Get authentication status

Returns the current authentication state for CLI sessions.

Responses

200 Authentication status

Schema (application/json)

object
3properties
authenticatedboolean
userobject
3properties
emailstring
namestring
tenant_idstring
expires_atstring<date-time>

curl -X GET 'https://shoehorn.example.com/api/v1/auth/cli/status' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/auth/cli/status', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/auth/cli/status',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/auth/cli/status", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Documentation API

v1.0.0

Per-service documentation discovered from repositories.

Base URL: https://shoehorn.example.com/api/v1

/

Documentation

GET /docs #

List documentation entries

Responses

200 Documentation entries discovered from repositories

curl -X GET 'https://shoehorn.example.com/api/v1/docs' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/docs', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/docs',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/docs", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /docs/{id} #

Get documentation content

Path parameters

idstringrequired

Responses

200 Documentation content

curl -X GET 'https://shoehorn.example.com/api/v1/docs/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/docs/{id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/docs/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/docs/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Entities API

v1.0.0

Entity CRUD operations, status, changelog, workloads, scorecards, and governance.

Base URL: https://shoehorn.example.com/api/v1

/

Entities

GET /entities #

List entities

Returns a paginated list of catalog entities.

Query parameters

limitinteger
cursorstring
type"service" | "library" | "api" | "website" | "tool" | "infrastructure" | "platform" | "mobile-app" | "data-pipeline" | "ml-model" | "documentation"
lifecycle"experimental" | "development" | "production" | "deprecated"
ownerstring
tier"tier1" | "tier2" | "tier3" | "tier4"

Responses

200 Paginated list of entities

Schema (application/json)

object
2properties
entitiesarray<Entity>
13properties
idstring<uuid>
service_idstring
Human-readable identifier
namestring
typestring
lifecyclestring
ownerstring
descriptionstring
tierstring
tagsarray<string>
linksarray<Link>
3properties
titlestring
urlstring<uri>
iconstring
sourcestring
"kubernetes""manifest""api""github""manual"
created_atstring<date-time>
updated_atstring<date-time>
paginationPagination
4properties
totalinteger
pageinteger
pageSizeinteger
nextCursorstring

curl -X GET 'https://shoehorn.example.com/api/v1/entities' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id} #

Get entity by ID

Path parameters

idstringrequired

Responses

200 Entity details

Schema (application/json)

Entity
13properties
idstring<uuid>
service_idstring
Human-readable identifier
namestring
typestring
lifecyclestring
ownerstring
descriptionstring
tierstring
tagsarray<string>
linksarray<Link>
3properties
titlestring
urlstring<uri>
iconstring
sourcestring
"kubernetes""manifest""api""github""manual"
created_atstring<date-time>
updated_atstring<date-time>
404 Entity not found

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /entities/{id} #

Update entity

Path parameters

idstringrequired

Request body required

Content-Type: application/json

EntityUpdate

6properties

namestring

descriptionstring

ownerstring

lifecyclestring

tierstring

tagsarray<string>

Responses

200 Updated entity

curl -X PUT 'https://shoehorn.example.com/api/v1/entities/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/entities/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/entities/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /entities/{id} #

Delete entity

Path parameters

idstringrequired

Responses

204 Entity deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/entities/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/entities/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/entities/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/readme #

Get entity README

Path parameters

idstringrequired

Responses

200 README content

Schema (application/json)

object
2properties
contentstring
formatstring
"markdown""html"

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/readme' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/readme', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/readme',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/readme", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/manifest #

Get entity manifest

Path parameters

idstringrequired

Responses

200 Entity manifest YAML

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/manifest' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/manifest', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/manifest',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/manifest", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/changelog #

Get entity changelog

Path parameters

idstringrequired

Responses

200 Changelog entries

Schema (application/json)

object
1property
entriesarray<ChangelogEntry>
7properties
idstring
timestampstring<date-time>
actionstring
fieldstring
old_valuestring
new_valuestring
actorstring

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/changelog' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/changelog', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/changelog',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/changelog", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/status #

Get entity status

Path parameters

idstringrequired

Responses

200 Entity health and status

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/status' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/status', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/status',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/status", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/deployments #

Get entity deployments

Path parameters

idstringrequired

Responses

200 Deployment history

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/deployments' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/deployments', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/deployments',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/deployments", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/resources #

Get entity resources

Returns associated cloud and infrastructure resources for an entity.

Path parameters

idstringrequired

Responses

200 Associated resources

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/resources' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/resources', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/resources',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/resources", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/k8s/workloads #

Get entity K8s workloads

Path parameters

idstringrequired

Responses

200 Kubernetes workload instances

Schema (application/json)

object
1property
instancesarray<WorkloadInstance>
8properties
cluster_idstring
namespacestring
namestring
kindstring
"Deployment""StatefulSet""DaemonSet""CronJob""Job"
replicasinteger
ready_replicasinteger
imagestring
last_seenstring<date-time>

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/k8s/workloads' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/k8s/workloads', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/k8s/workloads',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/k8s/workloads", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/quick-actions #

Get entity quick actions

Path parameters

idstringrequired

Responses

200 Available quick actions

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/quick-actions' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/quick-actions', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/quick-actions',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/quick-actions", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/scorecard #

Get entity scorecard

Path parameters

idstringrequired

Responses

200 Scorecard results with grade and category scores

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/scorecard' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/scorecard', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/scorecard',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/scorecard", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/governance/actions #

Get governance actions for entity

Path parameters

idstringrequired

Responses

200 Governance actions targeting this entity

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/governance/actions' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/governance/actions', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/governance/actions',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/governance/actions", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/zombies #

Get zombie workloads for entity

Path parameters

idstringrequired

Responses

200 Zombie (unowned) workloads associated with entity

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/zombies' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/zombies', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/zombies',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/zombies", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/activity #

Get entity activity feed

Path parameters

idstringrequired

Responses

200 Activity timeline

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/activity' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/activity', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/activity',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/activity", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/incidents #

Get entity incidents

Path parameters

idstringrequired

Responses

200 Incidents associated with entity

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/incidents' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/incidents', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/incidents',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/incidents", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/oncall #

Get entity on-call schedule

Path parameters

idstringrequired

Responses

200 On-call information

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/oncall' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/oncall', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/oncall',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/oncall", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/relations #

Get entity relations

Path parameters

idstringrequired

Responses

200 Entity dependency and relationship graph

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/relations' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/relations', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/relations',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/relations", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/topology #

Get entity service topology

Path parameters

idstringrequired

Responses

200 Network topology for entity

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/topology' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/topology', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/topology',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/topology", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/{id}/docs #

Get entity documentation

Path parameters

idstringrequired

Responses

200 Documentation entries for entity

curl -X GET 'https://shoehorn.example.com/api/v1/entities/{id}/docs' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/{id}/docs', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/{id}/docs',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/{id}/docs", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /entities/summary #

Get entities summary statistics

Responses

200 Summary counts by type, lifecycle, tier

curl -X GET 'https://shoehorn.example.com/api/v1/entities/summary' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/entities/summary', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/entities/summary',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/entities/summary", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Forge API

v1.0.0

Workflow engine for scaffolding, automation, and self-service actions. Molds are templates; runs are workflow executions.

Base URL: https://shoehorn.example.com/api/v1

/

Molds

GET /forge/molds #

List molds

Returns available workflow templates.

Query parameters

categorystring
publishedboolean

Responses

200 List of molds

curl -X GET 'https://shoehorn.example.com/api/v1/forge/molds' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/molds', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/forge/molds',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/forge/molds", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /forge/molds #

Create mold

Request body required

Content-Type: application/json

CreateMoldRequest

8properties

namestring*

slugstring*

descriptionstring

categorystring

iconstring

parametersarray<MoldParameter>

7properties

namestring*

typestring*

"string""number""boolean""select""multi-select"

labelstring

descriptionstring

requiredboolean

Default: false

defaultany

optionsarray<string>

Options for select/multi-select types

actionsarray<MoldAction>

3properties

namestring*

typestring*

"github-action""api-call""script""approval"

configobject

requires_approvalboolean

Default: false

Responses

201 Mold created

curl -X POST 'https://shoehorn.example.com/api/v1/forge/molds' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/molds', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/forge/molds',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/forge/molds", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

GET /forge/molds/{slug} #

Get mold by slug

Path parameters

slugstringrequired

Responses

200 Mold details including actions and parameters

curl -X GET 'https://shoehorn.example.com/api/v1/forge/molds/{slug}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/molds/{slug}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/forge/molds/{slug}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/forge/molds/{slug}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /forge/molds/{slug} #

Update mold

Path parameters

slugstringrequired

Request body required

Content-Type: application/json

UpdateMoldRequest

6properties

namestring

descriptionstring

categorystring

parametersarray<MoldParameter>

7properties

namestring*

typestring*

"string""number""boolean""select""multi-select"

labelstring

descriptionstring

requiredboolean

Default: false

defaultany

optionsarray<string>

Options for select/multi-select types

actionsarray<MoldAction>

3properties

namestring*

typestring*

"github-action""api-call""script""approval"

configobject

requires_approvalboolean

Responses

200 Mold updated

curl -X PUT 'https://shoehorn.example.com/api/v1/forge/molds/{slug}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/molds/{slug}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/forge/molds/{slug}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/forge/molds/{slug}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /forge/molds/{slug} #

Delete mold

Path parameters

slugstringrequired

Responses

204 Mold deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/forge/molds/{slug}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/molds/{slug}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/forge/molds/{slug}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/forge/molds/{slug}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /forge/molds/{slug}/publish #

Publish mold

Makes the mold visible to all users.

Path parameters

slugstringrequired

Responses

200 Mold published

curl -X POST 'https://shoehorn.example.com/api/v1/forge/molds/{slug}/publish' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/molds/{slug}/publish', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/forge/molds/{slug}/publish',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/forge/molds/{slug}/publish", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /forge/molds/{slug}/unpublish #

Unpublish mold

Path parameters

slugstringrequired

Responses

200 Mold unpublished

curl -X POST 'https://shoehorn.example.com/api/v1/forge/molds/{slug}/unpublish' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/molds/{slug}/unpublish', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/forge/molds/{slug}/unpublish',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/forge/molds/{slug}/unpublish", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Runs

GET /forge/runs #

List workflow runs

Query parameters

mold_slugstring
status"pending" | "running" | "completed" | "failed" | "cancelled" | "awaiting_approval"
limitinteger
cursorstring

Responses

200 Paginated workflow runs

curl -X GET 'https://shoehorn.example.com/api/v1/forge/runs' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/runs', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/forge/runs',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/forge/runs", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /forge/runs #

Execute a workflow

Creates and starts a new workflow run from a mold.

Request body required

Content-Type: application/json

object

2properties

mold_slugstring*

parametersobject*

User-provided parameter values

Responses

201 Run created and started

curl -X POST 'https://shoehorn.example.com/api/v1/forge/runs' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/runs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/forge/runs',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/forge/runs", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

GET /forge/runs/{runId} #

Get run details

Path parameters

runIdstringrequired

Responses

200 Run details with step statuses

curl -X GET 'https://shoehorn.example.com/api/v1/forge/runs/{runId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/runs/{runId}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/forge/runs/{runId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/forge/runs/{runId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /forge/runs/{runId}/cancel #

Cancel a running workflow

Path parameters

runIdstringrequired

Responses

200 Run cancelled

curl -X POST 'https://shoehorn.example.com/api/v1/forge/runs/{runId}/cancel' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/runs/{runId}/cancel', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/forge/runs/{runId}/cancel',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/forge/runs/{runId}/cancel", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /forge/runs/{runId}/approve #

Approve a pending workflow

Approves a workflow that is in awaiting_approval state.

Path parameters

runIdstringrequired

Responses

200 Run approved and resumed

curl -X POST 'https://shoehorn.example.com/api/v1/forge/runs/{runId}/approve' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/runs/{runId}/approve', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/forge/runs/{runId}/approve',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/forge/runs/{runId}/approve", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /forge/runs/{runId}/reject #

Reject a pending workflow

Path parameters

runIdstringrequired

Responses

200 Run rejected

curl -X POST 'https://shoehorn.example.com/api/v1/forge/runs/{runId}/reject' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/runs/{runId}/reject', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/forge/runs/{runId}/reject',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/forge/runs/{runId}/reject", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /forge/runs/{runId}/logs #

Get run execution logs

Path parameters

runIdstringrequired

Responses

200 Execution logs

curl -X GET 'https://shoehorn.example.com/api/v1/forge/runs/{runId}/logs' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/runs/{runId}/logs', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/forge/runs/{runId}/logs',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/forge/runs/{runId}/logs", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Forge Stats

GET /forge/stats #

Get forge statistics

Responses

200 Workflow execution statistics

curl -X GET 'https://shoehorn.example.com/api/v1/forge/stats' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/forge/stats', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/forge/stats',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/forge/stats", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Governance API

v1.0.0

Governance actions, dashboard metrics, and documentation health.

Base URL: https://shoehorn.example.com/api/v1

/

Governance

GET /governance/dashboard #

Get governance dashboard

Returns aggregate metrics for governance actions across all entities.

Responses

200 Dashboard metrics

Schema (application/json)

object
3properties
total_actionsinteger
by_statusobject
5properties
openinteger
in_progressinteger
resolvedinteger
dismissedinteger
wont_fixinteger
by_priorityobject
4properties
criticalinteger
highinteger
mediuminteger
lowinteger

curl -X GET 'https://shoehorn.example.com/api/v1/governance/dashboard' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/governance/dashboard', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/governance/dashboard',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/governance/dashboard", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /governance/documentation #

Get documentation health

Returns documentation coverage and freshness metrics.

Responses

200 Documentation health metrics

curl -X GET 'https://shoehorn.example.com/api/v1/governance/documentation' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/governance/documentation', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/governance/documentation',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/governance/documentation", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Governance Actions

GET /governance/actions #

List governance actions

Query parameters

status"open" | "in_progress" | "resolved" | "dismissed" | "wont_fix"
priority"critical" | "high" | "medium" | "low"
typestring
entity_idstring
assigned_tostring
overdueboolean
Only overdue actions when true.
closedboolean
Only closed actions (resolved, dismissed, wont_fix) when true. Can't be combined with a filter that only matches active actions.
actionableboolean
Only open and in_progress actions when true.
limitinteger
cursorstring

Responses

200 Paginated governance actions

Schema (application/json)

object
2properties
actionsarray<GovernanceAction>
14properties
idstring<uuid>
titlestring
descriptionstring
typestring
statusstring
"open""in_progress""resolved""dismissed""wont_fix"
prioritystring
"critical""high""medium""low"
entity_idstring
entity_namestring
assigned_tostring
created_bystring
due_datestring<date>
resolution_notesstring
created_atstring<date-time>
updated_atstring<date-time>
paginationobject
2properties
totalinteger
nextCursorstring

curl -X GET 'https://shoehorn.example.com/api/v1/governance/actions' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/governance/actions', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/governance/actions',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/governance/actions", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /governance/actions #

Create governance action

Request body required

Content-Type: application/json

CreateActionRequest

7properties

titlestring*

descriptionstring

typestring*

prioritystring*

"critical""high""medium""low"

entity_idstring

assigned_tostring

due_datestring<date>

Responses

201 Action created

curl -X POST 'https://shoehorn.example.com/api/v1/governance/actions' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/governance/actions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/governance/actions',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/governance/actions", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

POST /governance/actions/bulk #

Bulk update governance action status

Transition many actions to a single status in one request. Actions already in a final state are skipped.

Request body required

Content-Type: application/json

object

2properties

idsarray<string>*

statusstring*

"open""in_progress""resolved""dismissed""wont_fix"

Responses

200 Bulk update result

Schema (application/json)

object
2properties
requestedinteger
updatedinteger

curl -X POST 'https://shoehorn.example.com/api/v1/governance/actions/bulk' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/governance/actions/bulk', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/governance/actions/bulk',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/governance/actions/bulk", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

GET /governance/actions/{id} #

Get governance action

Path parameters

idstringrequired

Responses

200 Action details

curl -X GET 'https://shoehorn.example.com/api/v1/governance/actions/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/governance/actions/{id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/governance/actions/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/governance/actions/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PATCH /governance/actions/{id} #

Update governance action

Update status, priority, assignee, or add notes.

Path parameters

idstringrequired

Request body required

Content-Type: application/json

UpdateActionRequest

5properties

statusstring

"open""in_progress""resolved""dismissed""wont_fix"

prioritystring

"critical""high""medium""low"

assigned_tostring

resolution_notesstring

due_datestring<date>

Responses

200 Action updated

curl -X PATCH 'https://shoehorn.example.com/api/v1/governance/actions/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/governance/actions/{id}', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.patch(
    'https://shoehorn.example.com/api/v1/governance/actions/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("PATCH", "https://shoehorn.example.com/api/v1/governance/actions/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /governance/actions/{id} #

Delete governance action (soft delete)

Path parameters

idstringrequired

Responses

204 Action deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/governance/actions/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/governance/actions/{id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/governance/actions/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/governance/actions/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Groups API

v1.0.0

Identity provider groups and their role mappings. Group membership comes from the IdP; role mappings live in Shoehorn.

Base URL: https://shoehorn.example.com/api/v1

/

Groups

GET /groups #

List IdP groups

Returns all identity provider groups known to the system.

Responses

200 IdP groups

Schema (application/json)

object
1property
groupsarray<Group>
4properties
namestring
providerstring
"zitadel""okta""entra-id""keycloak"
member_countinteger
rolesarray<string>

curl -X GET 'https://shoehorn.example.com/api/v1/groups' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/groups', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/groups',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/groups", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /groups/{groupName}/roles #

Get group role mappings

Returns roles assigned to a specific IdP group.

Path parameters

groupNamestringrequired

Responses

200 Roles mapped to this group

Schema (application/json)

object
1property
rolesarray<string>

curl -X GET 'https://shoehorn.example.com/api/v1/groups/{groupName}/roles' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/groups/{groupName}/roles', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/groups/{groupName}/roles',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/groups/{groupName}/roles", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /groups/{groupName}/roles #

Assign role to group

Maps a role to an IdP group. All users in the group receive this role.

Path parameters

groupNamestringrequired

Request body required

Content-Type: application/json

object

1property

rolestring*

Responses

201 Role assigned to group

curl -X POST 'https://shoehorn.example.com/api/v1/groups/{groupName}/roles' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/groups/{groupName}/roles', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/groups/{groupName}/roles',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/groups/{groupName}/roles", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /groups/{groupName}/roles/{roleName} #

Remove role from group

Path parameters

groupNamestringrequired
roleNamestringrequired

Responses

204 Role removed from group

curl -X DELETE 'https://shoehorn.example.com/api/v1/groups/{groupName}/roles/{roleName}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/groups/{groupName}/roles/{roleName}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/groups/{groupName}/roles/{roleName}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/groups/{groupName}/roles/{roleName}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Indexing API

v1.0.0

Search-index health and reindex status.

Base URL: https://shoehorn.example.com/api/v1

/

Indexing

GET /indexing/status #

Get search indexing status

Responses

200 Current indexing status and queue size

curl -X GET 'https://shoehorn.example.com/api/v1/indexing/status' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/indexing/status', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/indexing/status',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/indexing/status", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Integrations API

v1.0.0

Integration management, webhooks, and sync operations.

Base URL: https://shoehorn.example.com/api/v1

/

Integrations

GET /integrations #

List integrations

Responses

200 List of configured integrations

Schema (application/json)

object
1property
integrationsarray<Integration>
7properties
idstring<uuid>
namestring
typestring
"github""gitlab""pagerduty""opsgenie""datadog""custom"
statusstring
"active""inactive""error"
configobject
last_syncstring<date-time>
created_atstring<date-time>

curl -X GET 'https://shoehorn.example.com/api/v1/integrations' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/integrations',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/integrations", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /integrations #

Create integration

Request body required

Content-Type: application/json

CreateIntegrationRequest

3properties

namestring*

typestring*

configobject*

Responses

201 Integration created

curl -X POST 'https://shoehorn.example.com/api/v1/integrations' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/integrations',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/integrations", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

GET /integrations/configs #

List integration configurations

Returns user-created integration configurations (as opposed to system integrations).

Responses

200 Integration configurations

Schema (application/json)

object
1property
configsarray<Integration>
7properties
idstring<uuid>
namestring
typestring
"github""gitlab""pagerduty""opsgenie""datadog""custom"
statusstring
"active""inactive""error"
configobject
last_syncstring<date-time>
created_atstring<date-time>

curl -X GET 'https://shoehorn.example.com/api/v1/integrations/configs' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations/configs', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/integrations/configs',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/integrations/configs", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /integrations/{id} #

Get integration details

Path parameters

idstringrequired

Responses

200 Integration details

curl -X GET 'https://shoehorn.example.com/api/v1/integrations/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations/{id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/integrations/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/integrations/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /integrations/{id} #

Update integration

Path parameters

idstringrequired

Request body required

Content-Type: application/json

UpdateIntegrationRequest

3properties

namestring

configobject

statusstring

Responses

200 Integration updated

curl -X PUT 'https://shoehorn.example.com/api/v1/integrations/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations/{id}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/integrations/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/integrations/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /integrations/{id} #

Delete integration

Path parameters

idstringrequired

Responses

204 Integration deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/integrations/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations/{id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/integrations/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/integrations/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /integrations/{id}/sync #

Trigger manual sync

Forces an immediate data pull from the integration source.

Path parameters

idstringrequired

Responses

200 Sync initiated

curl -X POST 'https://shoehorn.example.com/api/v1/integrations/{id}/sync' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations/{id}/sync', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/integrations/{id}/sync',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/integrations/{id}/sync", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Webhooks

GET /integrations/{id}/webhooks #

List webhooks for integration

Path parameters

idstringrequired

Responses

200 Webhooks configured for this integration

curl -X GET 'https://shoehorn.example.com/api/v1/integrations/{id}/webhooks' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations/{id}/webhooks', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/integrations/{id}/webhooks',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/integrations/{id}/webhooks", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /integrations/{id}/webhooks #

Create webhook

Path parameters

idstringrequired

Request body required

Content-Type: application/json

CreateWebhookRequest

3properties

urlstring<uri>*

eventsarray<string>*

secretstring

Responses

201 Webhook created

curl -X POST 'https://shoehorn.example.com/api/v1/integrations/{id}/webhooks' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations/{id}/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/integrations/{id}/webhooks',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/integrations/{id}/webhooks", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

PUT /integrations/webhooks/{webhookId} #

Update webhook

Path parameters

webhookIdstringrequired

Request body required

Content-Type: application/json

UpdateWebhookRequest

3properties

urlstring<uri>

eventsarray<string>

activeboolean

Responses

200 Webhook updated

curl -X PUT 'https://shoehorn.example.com/api/v1/integrations/webhooks/{webhookId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations/webhooks/{webhookId}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/integrations/webhooks/{webhookId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/integrations/webhooks/{webhookId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /integrations/webhooks/{webhookId} #

Delete webhook

Path parameters

webhookIdstringrequired

Responses

204 Webhook deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/integrations/webhooks/{webhookId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations/webhooks/{webhookId}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/integrations/webhooks/{webhookId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/integrations/webhooks/{webhookId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /integrations/github/webhook #

GitHub webhook receiver

Endpoint that receives GitHub webhook events. Verified using the webhook secret signature (X-Hub-Signature-256 header).

Responses

200 Event processed

curl -X POST 'https://shoehorn.example.com/api/v1/integrations/github/webhook' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/integrations/github/webhook', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/integrations/github/webhook',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/integrations/github/webhook", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Kubernetes API

v1.0.0

K8s agent registration, workload push, and heartbeat. (Network flow push is deprecated.)

Base URL: https://shoehorn.example.com/api/v1

/

K8s Agents

GET /k8s/agents #

List registered K8s agents

Responses

200 List of registered agents

Schema (application/json)

object
1property
agentsarray<Agent>
10properties
cluster_idstring
display_namestring
environmentstring
regionstring
statusstring
"active""stale""offline"
last_heartbeatstring<date-time>
agent_versionstring
node_countinteger
workload_countinteger
created_atstring<date-time>

curl -X GET 'https://shoehorn.example.com/api/v1/k8s/agents' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/agents', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/k8s/agents',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/k8s/agents", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /k8s/agents/register #

Register a new K8s agent

Registers a cluster and returns an agent token for push operations.

Request body required

Content-Type: application/json

object

4properties

cluster_idstring*

display_namestring*

environmentstring

regionstring

Responses

201 Agent registered

Schema (application/json)

object
2properties
cluster_idstring
tokenstring
Bearer token for push API

curl -X POST 'https://shoehorn.example.com/api/v1/k8s/agents/register' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/agents/register', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/k8s/agents/register',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/k8s/agents/register", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

GET /k8s/agents/{cluster_id} #

Get agent details

Path parameters

cluster_idstringrequired

Responses

200 Agent details

curl -X GET 'https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DELETE /k8s/agents/{cluster_id} #

Delete agent and all associated data

Path parameters

cluster_idstringrequired

Responses

204 Agent deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /k8s/agents/{cluster_id}/rotate #

Rotate agent token

Generates a new token and invalidates the previous one.

Path parameters

cluster_idstringrequired

Responses

200 New token generated

Schema (application/json)

object
1property
tokenstring

curl -X POST 'https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}/rotate' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}/rotate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}/rotate',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}/rotate", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /k8s/agents/{cluster_id}/revoke #

Revoke agent token

Revokes the agent token without deleting the agent record.

Path parameters

cluster_idstringrequired

Responses

200 Token revoked

curl -X POST 'https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}/revoke' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}/revoke', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}/revoke',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/k8s/agents/{cluster_id}/revoke", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

K8s Agent Push

POST /k8s/agents/push #

Push workload data from agent

Called by the K8s agent to push discovered workloads. Authenticated via agent bearer token (not session auth).

Request body required

Content-Type: application/json

object

2properties

cluster_idstring*

workloadsarray<Workload>*

9properties

namestring

namespacestring

kindstring

"Deployment""StatefulSet""DaemonSet""CronJob""Job"

labelsobject

annotationsobject

replicasinteger

ready_replicasinteger

imagesarray<string>

conditionsarray<object>

3properties

typestring

statusstring

reasonstring

Responses

200 Workloads received

curl -X POST 'https://shoehorn.example.com/api/v1/k8s/agents/push' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/agents/push', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/k8s/agents/push',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/k8s/agents/push", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

POST /k8s/agents/heartbeat #

Agent heartbeat

Called periodically by the agent to indicate it is alive.

Request body required

Content-Type: application/json

object

4properties

cluster_idstring*

agent_versionstring

node_countinteger

pod_countinteger

Responses

200 Heartbeat acknowledged

curl -X POST 'https://shoehorn.example.com/api/v1/k8s/agents/heartbeat' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/agents/heartbeat', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/k8s/agents/heartbeat',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/k8s/agents/heartbeat", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

POST /k8s/agents/{clusterId}/network-flows #

Push network flow data

**Deprecated.** The network observer that pushed these flows is retired in favor of platform-side relation inference. Already-deployed observers may still call this, so it stays until a future major version. Responses carry a `Deprecation: true` header (RFC 8594).

Path parameters

clusterIdstringrequired

Request body required

Content-Type: application/json

object

1property

flowsarray<object>

5properties

sourcestring

destinationstring

portinteger

protocolstring

bytes_sentinteger

Responses

200 Network flows received

curl -X POST 'https://shoehorn.example.com/api/v1/k8s/agents/{clusterId}/network-flows' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/agents/{clusterId}/network-flows', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/k8s/agents/{clusterId}/network-flows',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/k8s/agents/{clusterId}/network-flows", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Shoehorn Manifests API

v1.0.0

Create, validate, analyze, and convert catalog manifests (`.shoehorn/manifest.yml`).

Base URL: https://shoehorn.example.com/api/v1

/

Manifests

GET /manifests #

List manifests

Responses

200 All manifests

curl -X GET 'https://shoehorn.example.com/api/v1/manifests' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/manifests', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/manifests',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/manifests", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /manifests #

Create manifest

Request body required

Content-Type: application/json

ManifestInput

2properties

contentstring*

YAML manifest content

formatstring

"shoehorn""backstage"

Default: "shoehorn"

Responses

201 Manifest created

curl -X POST 'https://shoehorn.example.com/api/v1/manifests' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/manifests', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/manifests',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/manifests", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

GET /manifests/{id} #

Get manifest

Path parameters

idstringrequired

Responses

200 Manifest details

curl -X GET 'https://shoehorn.example.com/api/v1/manifests/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/manifests/{id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/manifests/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/manifests/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /manifests/{id} #

Update manifest

Path parameters

idstringrequired

Responses

200 Manifest updated

curl -X PUT 'https://shoehorn.example.com/api/v1/manifests/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/manifests/{id}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/manifests/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/manifests/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DELETE /manifests/{id} #

Delete manifest

Path parameters

idstringrequired

Responses

204 Manifest deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/manifests/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/manifests/{id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/manifests/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/manifests/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /manifests/validate #

Validate manifest

Validates a manifest YAML against the schema without creating it.

Request body required

Content-Type: application/json

ManifestInput

2properties

contentstring*

YAML manifest content

formatstring

"shoehorn""backstage"

Default: "shoehorn"

Responses

200 Validation results

Schema (application/json)

object
2properties
validboolean
errorsarray<object>
2properties
fieldstring
messagestring

curl -X POST 'https://shoehorn.example.com/api/v1/manifests/validate' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/manifests/validate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/manifests/validate',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/manifests/validate", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

POST /manifests/analyze #

Analyze manifest quality

Returns quality score and improvement suggestions.

Request body required

Content-Type: application/json

ManifestInput

2properties

contentstring*

YAML manifest content

formatstring

"shoehorn""backstage"

Default: "shoehorn"

Responses

200 Quality analysis

curl -X POST 'https://shoehorn.example.com/api/v1/manifests/analyze' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/manifests/analyze', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/manifests/analyze',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/manifests/analyze", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

POST /manifests/convert #

Convert Backstage catalog-info.yaml

Converts a Backstage catalog-info.yaml to Shoehorn manifest format.

Request body required

Content-Type: application/json

object

1property

contentstring

Raw YAML content

Responses

200 Converted manifest

curl -X POST 'https://shoehorn.example.com/api/v1/manifests/convert' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/manifests/convert', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/manifests/convert',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/manifests/convert", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Shoehorn Marketplace API

v1.0.0

Addon marketplace browsing, installation, configuration, and runtime management. Addons extend Shoehorn with custom integrations, widgets, and backend logic.

Base URL: https://shoehorn.example.com/api/v1

/

Marketplace

GET /marketplace #

List marketplace catalog

Returns available addons in the marketplace, optionally filtered by kind.

Query parameters

kind"addon" | "widget" | "integration"
Filter by addon kind
categorystring
searchstring

Responses

200 Marketplace catalog

Schema (application/json)

object
1property
itemsarray<MarketplaceItem>
9properties
slugstring
namestring
descriptionstring
versionstring
authorstring
categorystring
tierstring
"free""pro""enterprise"
iconstring
installedboolean

curl -X GET 'https://shoehorn.example.com/api/v1/marketplace' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/marketplace', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/marketplace',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/marketplace", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /marketplace/installed #

List installed addons

Returns all addons currently installed in this tenant.

Responses

200 Installed addons

Schema (application/json)

object
1property
addonsarray<InstalledAddon>
7properties
slugstring
namestring
versionstring
enabledboolean
statusstring
"running""stopped""error"
installed_atstring<date-time>
configobject

curl -X GET 'https://shoehorn.example.com/api/v1/marketplace/installed' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/marketplace/installed', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/marketplace/installed',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/marketplace/installed", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /marketplace/install #

Install addon

Installs an addon from the marketplace by slug.

Request body required

Content-Type: application/json

object

1property

slugstring*

Addon slug from marketplace

Responses

201 Addon installed
409 Addon already installed

curl -X POST 'https://shoehorn.example.com/api/v1/marketplace/install' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/marketplace/install', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/marketplace/install',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/marketplace/install", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /marketplace/{slug}/uninstall #

Uninstall addon

Removes an installed addon and its configuration.

Path parameters

slugstringrequired

Responses

204 Addon uninstalled
404 Addon not found

curl -X DELETE 'https://shoehorn.example.com/api/v1/marketplace/{slug}/uninstall' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/marketplace/{slug}/uninstall', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/marketplace/{slug}/uninstall',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/marketplace/{slug}/uninstall", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /marketplace/{slug}/enable #

Enable addon

Re-enables a previously disabled addon.

Path parameters

slugstringrequired

Responses

200 Addon enabled

curl -X POST 'https://shoehorn.example.com/api/v1/marketplace/{slug}/enable' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/marketplace/{slug}/enable', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/marketplace/{slug}/enable',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/marketplace/{slug}/enable", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /marketplace/{slug}/disable #

Disable addon

Disables an addon without uninstalling it. Configuration is preserved.

Path parameters

slugstringrequired

Responses

200 Addon disabled

curl -X POST 'https://shoehorn.example.com/api/v1/marketplace/{slug}/disable' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/marketplace/{slug}/disable', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/marketplace/{slug}/disable',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/marketplace/{slug}/disable", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /marketplace/import-manifest #

Import addon manifest

Publishes an addon manifest to the marketplace. Used by addon developers.

Request body required

Content-Type: application/json

AddonManifest

4properties

schemaVersioninteger*

1

kindstring*

"addon"

metadataobject*

7properties

slugstring*

namestring*

versionstring*

descriptionstring*

authorobject*

categorystring*

tierstring*

addonobject*

6properties

tierstring*

"declarative""scripted""full"

runtimestring*

"quickjs"

permissionsobject*

syncobject

configobject

frontendobject

Responses

201 Manifest imported
422 Manifest validation failed

curl -X POST 'https://shoehorn.example.com/api/v1/marketplace/import-manifest' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/marketplace/import-manifest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/marketplace/import-manifest',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/marketplace/import-manifest", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

POST /marketplace/{slug}/bundle #

Upload addon bundle

Uploads backend and/or frontend bundles for a published addon. Uses multipart form upload with `backend` and `frontend` file fields.

Path parameters

slugstringrequired

Request body required

Content-Type: multipart/form-data

object

2properties

backendstring<binary>

Backend JS bundle (QuickJS IIFE)

frontendstring<binary>

Frontend JS bundle (ESM)

Responses

200 Bundle uploaded

curl -X POST 'https://shoehorn.example.com/api/v1/marketplace/{slug}/bundle' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/marketplace/{slug}/bundle', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/marketplace/{slug}/bundle',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/marketplace/{slug}/bundle", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Addon Runtime

GET /addons/{slug}/status #

Get addon runtime status

Returns the runtime status of an installed addon.

Path parameters

slugstringrequired

Responses

200 Addon status

Schema (application/json)

AddonStatus
7properties
slugstring
enabledboolean
statusstring
"running""stopped""error"
last_syncstring<date-time>
last_errorstring
items_syncedinteger
uptime_secondsinteger

curl -X GET 'https://shoehorn.example.com/api/v1/addons/{slug}/status' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/addons/{slug}/status', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/addons/{slug}/status',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/addons/{slug}/status", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /addons/{slug}/logs #

Get addon logs

Returns recent log entries from the addon runtime.

Path parameters

slugstringrequired

Query parameters

limitinteger

Responses

200 Addon logs

Schema (application/json)

object
1property
logsarray<LogEntry>
4properties
timestampstring<date-time>
levelstring
"debug""info""warn""error"
messagestring
fieldsobject

curl -X GET 'https://shoehorn.example.com/api/v1/addons/{slug}/logs' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/addons/{slug}/logs', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/addons/{slug}/logs',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/addons/{slug}/logs", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /addons/{slug}/{path} #

Call addon route (GET)

Proxies a GET request to the addon's handleRoute() function.

Path parameters

slugstringrequired
pathstringrequired

Responses

200 Addon response

curl -X GET 'https://shoehorn.example.com/api/v1/addons/{slug}/{path}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/addons/{slug}/{path}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/addons/{slug}/{path}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/addons/{slug}/{path}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /addons/{slug}/{path} #

Call addon route (POST)

Proxies a POST request to the addon's handleRoute() function.

Path parameters

slugstringrequired
pathstringrequired

Request body

Content-Type: application/json

Free-form JSON object (no fixed schema).

Responses

200 Addon response

curl -X POST 'https://shoehorn.example.com/api/v1/addons/{slug}/{path}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/addons/{slug}/{path}', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/addons/{slug}/{path}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/addons/{slug}/{path}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Shoehorn Metrics API

v1.0.0

Real-time platform metrics for dashboard widgets. The current implementation returns a mix of live counts (from the catalog) and mock values for response-time, system, and integration metrics. Responses include a `mock_data: true` flag wherever the values are synthetic. A future release will swap these for Prometheus-backed numbers.

Base URL: https://shoehorn.example.com/api/v1

/

Metrics

GET /metrics/ #

Get current platform metrics

Returns a snapshot of HTTP request counts, response-time samples, integration counts, and basic system stats. Used by the home and admin dashboards.

Responses

200 Metrics snapshot

Schema (application/json)

object
6properties
timestampstring<date-time>
http_requests_totalobject
Request counts keyed by HTTP method.
response_timesarray<object>
5properties
timestampstring<date-time>
methodstring
pathstring
response_time_msnumber
status_codeinteger
integrations_statsobject
4properties
totalinteger
activeinteger
errorsinteger
mock_databoolean
system_statsobject
6properties
database_connectionsinteger
cache_hitsinteger
cache_missesinteger
memory_usage_bytesinteger
cpu_usage_percentnumber
mock_databoolean
mock_databoolean
True if any field in the response is synthetic.

curl -X GET 'https://shoehorn.example.com/api/v1/metrics/' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/metrics/', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/metrics/',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/metrics/", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /metrics/timeseries #

Get a time-series for a named metric

Returns timestamps and values for a single metric over a window. Currently generates synthetic data; treat the shape as stable but the values as illustrative until the Prometheus backend lands.

Query parameters

metric"response_time" | "request_count" | "error_rate" | "cpu_usage" | "memory_usage"required
range"1h" | "24h" | "7d"

Responses

200 Time-series data

Schema (application/json)

object
4properties
metricstring
timeRangestring
timestampsarray<string<date-time>>
valuesarray<number>
400 metric query parameter missing

curl -X GET 'https://shoehorn.example.com/api/v1/metrics/timeseries' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/metrics/timeseries', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/metrics/timeseries',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/metrics/timeseries", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DORA

GET /metrics/dora #

Get DORA metrics

Deployment frequency, lead time for changes, mean time to restore, and change failure rate. Optionally filtered by team.

Query parameters

teamstring
period"7d" | "30d" | "90d"

Responses

200 DORA metrics (deployment frequency, lead time, MTTR, change failure rate)

curl -X GET 'https://shoehorn.example.com/api/v1/metrics/dora' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/metrics/dora', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/metrics/dora',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/metrics/dora", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Insights

GET /metrics/bus-factor #

Get bus factor analysis

Returns bus-factor scores per entity (or for a specific entity if `entity_id` is given). Higher score = more contributors who could keep the service running.

Query parameters

entity_idstring

Responses

200 Bus factor scores

curl -X GET 'https://shoehorn.example.com/api/v1/metrics/bus-factor' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/metrics/bus-factor', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/metrics/bus-factor',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/metrics/bus-factor", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Notifications API

v1.0.0

User notifications and notification subscription management.

Base URL: https://shoehorn.example.com/api/v1

/

Notifications

GET /notifications #

List notifications

Returns notifications visible to the current user.

Query parameters

severity"critical" | "warning" | "info"
typestring
Filter by notification type prefix
limitinteger
offsetinteger

Responses

200 User notifications

Schema (application/json)

object
1property
notificationsarray<Notification>
18properties
idstring<uuid>
tenantIdstring<uuid>
teamIdstring<uuid>nullable
entityIdintegernullable
notificationTypestring
Dotted type, e.g. k8s.workload.unhealthy
severitystring
"critical""warning""info"
titlestring
messagestring
actionUrlstring
Deep link to the related resource
metadataobject
isReadboolean
dedupeKeystringnullable
resolvedAtstring<date-time>nullable
expiresAtstring<date-time>nullable
tagsarray<string>
criticalityTierintegernullable
createdAtstring<date-time>
updatedAtstring<date-time>

curl -X GET 'https://shoehorn.example.com/api/v1/notifications' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/notifications',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/notifications", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /notifications/count #

Get unread notification counts

Returns unread notification counts grouped by severity.

Responses

200 Unread counts

Schema (application/json)

object
4properties
totalinteger
criticalinteger
warninginteger
infointeger

curl -X GET 'https://shoehorn.example.com/api/v1/notifications/count' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/count', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/notifications/count',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/notifications/count", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PATCH /notifications/{id}/read #

Mark notification as read

Path parameters

idstring<uuid>required

Responses

200 Notification marked as read

curl -X PATCH 'https://shoehorn.example.com/api/v1/notifications/{id}/read' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/{id}/read', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.patch(
    'https://shoehorn.example.com/api/v1/notifications/{id}/read',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("PATCH", "https://shoehorn.example.com/api/v1/notifications/{id}/read", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /notifications/read-all #

Mark all notifications as read

Responses

200 All notifications marked as read

curl -X POST 'https://shoehorn.example.com/api/v1/notifications/read-all' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/read-all', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/notifications/read-all',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/notifications/read-all", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

DELETE /notifications/{id} #

Dismiss notification

Path parameters

idstring<uuid>required

Responses

204 Notification dismissed

curl -X DELETE 'https://shoehorn.example.com/api/v1/notifications/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/{id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/notifications/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/notifications/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /notifications/dismiss-all #

Dismiss all notifications

Responses

200 Notifications dismissed

Schema (application/json)

object
1property
dismissedinteger

curl -X POST 'https://shoehorn.example.com/api/v1/notifications/dismiss-all' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/dismiss-all', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/notifications/dismiss-all',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/notifications/dismiss-all", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Notification Subscriptions

GET /notifications/subscriptions #

List notification subscriptions

Returns subscriptions for a team or user scope.

Query parameters

scope"team" | "user"required
scope_idstring<uuid>required

Responses

200 Subscriptions for the scope

Schema (application/json)

object
2properties
subscriptionsarray<Subscription>
16properties
idstring<uuid>
scopestring
"team""user"
scope_idstring<uuid>
namestring
enabledboolean
event_typesarray<string>
min_severitystring
"critical""warning""info"
entity_filterobject
channel_typestring
"slack""webhook""email""inapp"
channel_configobject
Channel settings; secret values are redacted in responses.
cadencestring
"realtime""hourly""daily""weekly"
cadence_configobject
paused_untilstring<date-time>nullable
next_due_atstring<date-time>nullable
created_atstring<date-time>
updated_atstring<date-time>
totalinteger

curl -X GET 'https://shoehorn.example.com/api/v1/notifications/subscriptions' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/subscriptions', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/notifications/subscriptions',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/notifications/subscriptions", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /notifications/subscriptions #

Create notification subscription

Request body required

Content-Type: application/json

SubscriptionInput

11properties

scopestring*

"team""user"

scope_idstring<uuid>*

namestring*

enabledboolean

Default: true

event_typesarray<string>*

min_severitystring

"critical""warning""info"

entity_filterobject

channel_typestring*

"slack""webhook""email""inapp"

channel_configobject

Channel settings. Secret values are encrypted on write.

cadencestring

"realtime""hourly""daily""weekly"

cadence_configobject

For non-realtime cadences: day_of_week (0-6), hour (0-23), minute (0-59).

Responses

201 Created subscription

Schema (application/json)

Subscription
16properties
idstring<uuid>
scopestring
"team""user"
scope_idstring<uuid>
namestring
enabledboolean
event_typesarray<string>
min_severitystring
"critical""warning""info"
entity_filterobject
channel_typestring
"slack""webhook""email""inapp"
channel_configobject
Channel settings; secret values are redacted in responses.
cadencestring
"realtime""hourly""daily""weekly"
cadence_configobject
paused_untilstring<date-time>nullable
next_due_atstring<date-time>nullable
created_atstring<date-time>
updated_atstring<date-time>

curl -X POST 'https://shoehorn.example.com/api/v1/notifications/subscriptions' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/subscriptions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/notifications/subscriptions',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/notifications/subscriptions", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

PUT /notifications/subscriptions/{id} #

Update notification subscription

Updates a subscription. The scope, scope_id, and channel_type fields are immutable.

Path parameters

idstring<uuid>required

Request body required

Content-Type: application/json

SubscriptionInput

11properties

scopestring*

"team""user"

scope_idstring<uuid>*

namestring*

enabledboolean

Default: true

event_typesarray<string>*

min_severitystring

"critical""warning""info"

entity_filterobject

channel_typestring*

"slack""webhook""email""inapp"

channel_configobject

Channel settings. Secret values are encrypted on write.

cadencestring

"realtime""hourly""daily""weekly"

cadence_configobject

For non-realtime cadences: day_of_week (0-6), hour (0-23), minute (0-59).

Responses

200 Updated subscription

Schema (application/json)

Subscription
16properties
idstring<uuid>
scopestring
"team""user"
scope_idstring<uuid>
namestring
enabledboolean
event_typesarray<string>
min_severitystring
"critical""warning""info"
entity_filterobject
channel_typestring
"slack""webhook""email""inapp"
channel_configobject
Channel settings; secret values are redacted in responses.
cadencestring
"realtime""hourly""daily""weekly"
cadence_configobject
paused_untilstring<date-time>nullable
next_due_atstring<date-time>nullable
created_atstring<date-time>
updated_atstring<date-time>
404 Subscription not found

curl -X PUT 'https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /notifications/subscriptions/{id} #

Delete notification subscription

Path parameters

idstring<uuid>required

Responses

204 Subscription deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /notifications/subscriptions/{id}/test #

Send a test notification

Sends a synthetic notification through the subscription's channel.

Path parameters

idstring<uuid>required

Responses

200 Test notification sent

Schema (application/json)

object
1property
statusstring
"sent"
502 Channel delivery failed

curl -X POST 'https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/test' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/test', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/test',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/test", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /notifications/subscriptions/{id}/resume #

Resume a paused subscription

Clears paused_until to resume delivery.

Path parameters

idstring<uuid>required

Responses

200 Subscription resumed

Schema (application/json)

object
1property
statusstring
"resumed"

curl -X POST 'https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/resume' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/resume', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/resume',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/resume", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /notifications/subscriptions/{id}/deliveries #

List subscription delivery attempts

Returns the 50 most recent delivery attempts for a subscription.

Path parameters

idstring<uuid>required

Responses

200 Recent delivery attempts

Schema (application/json)

object
2properties
deliveriesarray<Delivery>
8properties
notification_idstring<uuid>
channel_typestring
"slack""webhook""email""inapp"
statusstring
"pending""success""failed"
attemptsinteger
last_errorstringnullable
created_atstring<date-time>
delivered_atstring<date-time>nullable
next_attempt_atstring<date-time>nullable
totalinteger

curl -X GET 'https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/deliveries' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/deliveries', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/deliveries',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/notifications/subscriptions/{id}/deliveries", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Operations API

v1.0.0

Workloads, deployment tracking, and GitOps management.

Base URL: https://shoehorn.example.com/api/v1

/

Workloads

GET /operations/workloads #

List all workloads

Returns workloads across all registered K8s clusters.

Query parameters

cluster_idstring
namespacestring
kind"Deployment" | "StatefulSet" | "DaemonSet" | "CronJob" | "Job"
limitinteger
cursorstring

Responses

200 Paginated workloads

curl -X GET 'https://shoehorn.example.com/api/v1/operations/workloads' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/workloads', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/workloads',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/workloads", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/workloads/stats #

Get workload statistics

Responses

200 Workload aggregate statistics

Schema (application/json)

object
5properties
totalinteger
by_kindobject
by_clusterobject
healthyinteger
unhealthyinteger

curl -X GET 'https://shoehorn.example.com/api/v1/operations/workloads/stats' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/workloads/stats', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/workloads/stats',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/workloads/stats", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/workloads/image-stats #

Get image usage statistics

Returns aggregated container image statistics across workloads. All filters are optional and combine with AND.

Query parameters

clusterstring
namespacestring
teamstring
ownerstring

Responses

200 Image statistics

Schema (application/json)

object
4properties
total_imagesinteger
unique_imagesinteger
by_registryobject
outdatedinteger
Images older than the platform's freshness threshold
400 Invalid filter value

curl -X GET 'https://shoehorn.example.com/api/v1/operations/workloads/image-stats' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/workloads/image-stats', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/workloads/image-stats',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/workloads/image-stats", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/workloads/replica-stats #

Get replica health statistics

Returns aggregated replica health (desired vs ready) across workloads.

Query parameters

clusterstring
namespacestring
teamstring
ownerstring

Responses

200 Replica statistics

Schema (application/json)

object
4properties
desiredinteger
readyinteger
unavailableinteger
by_clusterobject

curl -X GET 'https://shoehorn.example.com/api/v1/operations/workloads/replica-stats' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/workloads/replica-stats', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/workloads/replica-stats',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/workloads/replica-stats", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/workloads/network-policy-stats #

Get network policy coverage statistics

Returns the share of workloads in a cluster covered by at least one NetworkPolicy.

Query parameters

clusterstringrequired

Responses

200 Coverage statistics

Schema (application/json)

object
5properties
clusterstring
total_workloadsinteger
coveredinteger
uncoveredinteger
coverage_percentnumber
400 cluster query parameter missing or too long
503 Network policy service not configured

curl -X GET 'https://shoehorn.example.com/api/v1/operations/workloads/network-policy-stats' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/workloads/network-policy-stats', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/workloads/network-policy-stats',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/workloads/network-policy-stats", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/workloads/{id} #

Get workload details

Path parameters

idstringrequired

Responses

200 Workload details including pods and events

curl -X GET 'https://shoehorn.example.com/api/v1/operations/workloads/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/workloads/{id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/workloads/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/workloads/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/workloads/{id}/pods #

Get workload pods

Path parameters

idstringrequired

Responses

200 Pods belonging to workload

curl -X GET 'https://shoehorn.example.com/api/v1/operations/workloads/{id}/pods' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/workloads/{id}/pods', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/workloads/{id}/pods',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/workloads/{id}/pods", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/workloads/{id}/events #

Get workload events

Path parameters

idstringrequired

Responses

200 Recent Kubernetes events for workload

curl -X GET 'https://shoehorn.example.com/api/v1/operations/workloads/{id}/events' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/workloads/{id}/events', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/workloads/{id}/events',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/workloads/{id}/events", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/workloads/{id}/network-flows #

Get inbound/outbound network flows for a workload

**Deprecated.** Superseded by platform-side relation inference. Retained for already-deployed observers until a future major version. Responses carry a `Deprecation: true` header (RFC 8594). Returns the inbound and outbound aggregated flows for a single workload entity.

Path parameters

idstringrequired

Query parameters

timeRangestring
minConnectionsinteger

Responses

200 Inbound and outbound flows for the workload
400 Invalid workload ID
404 Workload not found
503 Network flow service not configured

curl -X GET 'https://shoehorn.example.com/api/v1/operations/workloads/{id}/network-flows' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/workloads/{id}/network-flows', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/workloads/{id}/network-flows',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/workloads/{id}/network-flows", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/zombies #

List zombie workloads

Returns workloads that are not matched to any catalog entity (unowned).

Query parameters

cluster_idstring
namespacestring

Responses

200 Unowned workloads

curl -X GET 'https://shoehorn.example.com/api/v1/operations/zombies' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/zombies', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/zombies',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/zombies", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GitOps

GET /operations/gitops #

List GitOps resources

Returns ArgoCD Applications and FluxCD resources across clusters.

Query parameters

platform"argocd" | "fluxcd"
cluster_idstring
sync_status"synced" | "out_of_sync" | "unknown"
health_status"healthy" | "degraded" | "progressing" | "missing" | "unknown"

Responses

200 GitOps resources

curl -X GET 'https://shoehorn.example.com/api/v1/operations/gitops' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/gitops', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/gitops',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/gitops", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/gitops/stats #

Get GitOps statistics

Responses

200 Aggregate GitOps statistics

curl -X GET 'https://shoehorn.example.com/api/v1/operations/gitops/stats' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/gitops/stats', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/gitops/stats',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/gitops/stats", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/gitops/{id} #

Get GitOps resource details

Path parameters

idstringrequired

Responses

200 GitOps resource details

curl -X GET 'https://shoehorn.example.com/api/v1/operations/gitops/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/gitops/{id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/gitops/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/gitops/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /operations/gitops/{id}/sync #

Trigger GitOps sync

Sends a sync command to the agent managing this resource.

Path parameters

idstringrequired

Responses

200 Sync command queued

curl -X POST 'https://shoehorn.example.com/api/v1/operations/gitops/{id}/sync' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/gitops/{id}/sync', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/operations/gitops/{id}/sync',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/operations/gitops/{id}/sync", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /operations/gitops/{id}/refresh #

Trigger GitOps refresh

Sends a refresh command to re-evaluate desired state.

Path parameters

idstringrequired

Responses

200 Refresh command queued

curl -X POST 'https://shoehorn.example.com/api/v1/operations/gitops/{id}/refresh' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/gitops/{id}/refresh', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/operations/gitops/{id}/refresh',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/operations/gitops/{id}/refresh", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

NetworkFlows

GET /operations/clusters/{clusterId}/network-flows #

List aggregated network flows for a cluster

**Deprecated.** The network observer that fed these flows is retired in favor of platform-side relation inference. Already-deployed observers may still POST flows, so this endpoint stays until a future major version. Responses carry a `Deprecation: true` header (RFC 8594). Returns aggregated source-to-destination flows. Backed by the network flow service; returns `503` if that service is not configured.

Path parameters

clusterIdstringrequired

Query parameters

timeRangestring
Window over which to aggregate. Examples: `15m`, `1h`, `24h`.
minConnectionsinteger
Drop edges below this connection count.
pageinteger
pageSizeinteger

Responses

200 Aggregated flows

Schema (application/json)

object
2properties
flowsarray<object>
5properties
sourceEntityIdstring
destEntityIdstring
destPortinteger
connectionCountinteger
lastSeenAtstring<date-time>
metaobject
2properties
timeRangestring
totalFlowsinteger
400 clusterId missing
503 Network flow service not configured

curl -X GET 'https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/clusters/{clusterId}/network-flows/topology #

Get the network topology graph for a cluster

**Deprecated.** Superseded by platform-side relation inference. Retained for already-deployed observers until a future major version. Responses carry a `Deprecation: true` header (RFC 8594). Returns nodes, edges, and summary stats suitable for graph rendering.

Path parameters

clusterIdstringrequired

Query parameters

timeRangestring
minConnectionsinteger
pageinteger
pageSizeinteger

Responses

200 Topology

Schema (application/json)

object
3properties
nodesarray<object>
edgesarray<object>
statsobject
400 clusterId missing
503 Network flow service not configured

curl -X GET 'https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows/topology' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows/topology', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows/topology',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows/topology", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /operations/clusters/{clusterId}/network-flows/stats #

Get summary statistics for a cluster's network flows

**Deprecated.** Superseded by platform-side relation inference. Retained for already-deployed observers until a future major version. Responses carry a `Deprecation: true` header (RFC 8594). Returns summary statistics (total flows, unique source/destination entities, and top talkers and ports) for network flows within a cluster.

Path parameters

clusterIdstringrequired

Query parameters

timeRangestring
minConnectionsinteger

Responses

200 Summary statistics
400 clusterId missing
503 Network flow service not configured

curl -X GET 'https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows/stats' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows/stats', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows/stats',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/operations/clusters/{clusterId}/network-flows/stats", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GitOps Agent

POST /k8s/gitops/push #

Push GitOps resources from agent

Called by the K8s agent to push discovered GitOps resources.

Responses

200 Resources received

curl -X POST 'https://shoehorn.example.com/api/v1/k8s/gitops/push' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/gitops/push', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/k8s/gitops/push',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/k8s/gitops/push", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /k8s/{clusterId}/gitops/commands #

Get pending GitOps commands for agent

Path parameters

clusterIdstringrequired

Responses

200 Pending commands (sync, refresh)

curl -X GET 'https://shoehorn.example.com/api/v1/k8s/{clusterId}/gitops/commands' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/{clusterId}/gitops/commands', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/k8s/{clusterId}/gitops/commands',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/k8s/{clusterId}/gitops/commands", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PATCH /k8s/{clusterId}/gitops/commands/{commandId} #

Update command status

Path parameters

clusterIdstringrequired
commandIdstringrequired

Responses

200 Command status updated

curl -X PATCH 'https://shoehorn.example.com/api/v1/k8s/{clusterId}/gitops/commands/{commandId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/k8s/{clusterId}/gitops/commands/{commandId}', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.patch(
    'https://shoehorn.example.com/api/v1/k8s/{clusterId}/gitops/commands/{commandId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("PATCH", "https://shoehorn.example.com/api/v1/k8s/{clusterId}/gitops/commands/{commandId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Organization API

v1.0.0

Org-chart endpoints. The read endpoint is available to all authenticated users; the write endpoint is admin-only.

Base URL: https://shoehorn.example.com/api/v1

/

OrgChart

GET /organization/org-chart #

Get the org chart

Returns every active team plus its parent relationship, member count, and the team's primary manager (the highest-ranking member matching owner / manager / lead / team_lead). `total_member_count` includes descendants. Sub-team links are computed server-side.

Responses

200 Org chart

Schema (application/json)

object
1property
teamsarray<OrgChartTeam>
12properties
idstring<uuid>
namestring
slugstring
display_namestringnullable
descriptionstringnullable
parent_team_idstring<uuid>nullable
sub_team_idsarray<string<uuid>>
member_countinteger
Direct members.
total_member_countinteger
Direct members plus all descendants.
manager_user_idstringnullable
Highest-ranking team member (owner > manager > lead > team_lead).
manager_rolestringnullable
metadataobject

curl -X GET 'https://shoehorn.example.com/api/v1/organization/org-chart' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/organization/org-chart', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/organization/org-chart',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/organization/org-chart", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /admin/org-chart #

Bulk-update team parent relationships

Admin-only. Each update sets a team's `parent_team_id`; pass `null` (or omit) to make the team a root team. Updates run inside one transaction. The server walks ancestry to reject cycles before applying: if any update would create a cycle, the entire request fails with `CIRCULAR_REFERENCE`.

Request body required

Content-Type: application/json

object

1property

updatesarray<object>*

2properties

team_idstring<uuid>*

parent_team_idstring<uuid>nullable

Set null to make the team a root team.

Responses

200 Updates applied

Schema (application/json)

object
2properties
successboolean
updatedinteger
Number of updates applied.
400 Returned for an empty `updates` array, an invalid UUID, or a cycle. Cycles use the error code `CIRCULAR_REFERENCE`.
403 Caller lacks admin permission

curl -X PUT 'https://shoehorn.example.com/api/v1/admin/org-chart' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/org-chart', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/admin/org-chart',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/admin/org-chart", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Shoehorn Search API

v1.0.0

Full-text search across catalog entities, teams, and documentation, powered by Meilisearch with sub-50ms fuzzy matching.

Base URL: https://shoehorn.example.com/api/v1

/

Search

GET /search #

Search entities

Full-text search across all catalog entities using Meilisearch.

Query parameters

qstringrequired
Search query (supports fuzzy matching)
typestring
Filter by entity type
lifecyclestring
ownerstring
limitinteger

Responses

200 Search results

Schema (application/json)

object
4properties
resultsarray<SearchResult>
8properties
idstring
service_idstring
namestring
typestring
descriptionstring
ownerstring
lifecyclestring
scorenumber
Relevance score
totalinteger
querystring
processing_time_msinteger

curl -X GET 'https://shoehorn.example.com/api/v1/search' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/search', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/search',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/search", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Security API

v1.0.0

Security overview, findings, and posture assessment.

Base URL: https://shoehorn.example.com/api/v1

/

Security

GET /security/overview #

Get security overview

Returns the overall security posture for the tenant, including entity counts by security grade, risk distribution, and trends.

Responses

200 Security overview

Schema (application/json)

object
4properties
overall_gradestring
"A+""A""B""C""D""F"
total_entitiesinteger
by_gradeobject
findings_summaryobject
5properties
criticalinteger
highinteger
mediuminteger
lowinteger
infointeger

curl -X GET 'https://shoehorn.example.com/api/v1/security/overview' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/security/overview', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/security/overview',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/security/overview", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /security/findings #

List security findings

Returns security findings across all entities.

Query parameters

severity"critical" | "high" | "medium" | "low" | "info"
entity_idstring
typestring
status"open" | "acknowledged" | "resolved" | "false_positive"
limitinteger
cursorstring

Responses

200 Paginated security findings

Schema (application/json)

object
2properties
findingsarray<SecurityFinding>
12properties
idstring<uuid>
entity_idstring
entity_namestring
typestring
e.g., missing_owner, no_readme, exposed_secret
severitystring
"critical""high""medium""low""info"
statusstring
"open""acknowledged""resolved""false_positive"
titlestring
descriptionstring
remediationstring
Suggested fix
sourcestring
e.g., scorecard, scanner, manual
created_atstring<date-time>
resolved_atstring<date-time>
paginationobject
2properties
totalinteger
nextCursorstring

curl -X GET 'https://shoehorn.example.com/api/v1/security/findings' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/security/findings', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/security/findings',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/security/findings", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /security/findings/{id} #

Get security finding details

Path parameters

idstringrequired

Responses

200 Finding details with remediation guidance

Schema (application/json)

SecurityFinding
12properties
idstring<uuid>
entity_idstring
entity_namestring
typestring
e.g., missing_owner, no_readme, exposed_secret
severitystring
"critical""high""medium""low""info"
statusstring
"open""acknowledged""resolved""false_positive"
titlestring
descriptionstring
remediationstring
Suggested fix
sourcestring
e.g., scorecard, scanner, manual
created_atstring<date-time>
resolved_atstring<date-time>

curl -X GET 'https://shoehorn.example.com/api/v1/security/findings/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/security/findings/{id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/security/findings/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/security/findings/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Teams API

v1.0.0

Team management, members, group mappings, and role assignments.

Base URL: https://shoehorn.example.com/api/v1

/

Teams

GET /teams #

List teams (public)

Returns teams visible to the current user.

Query parameters

limitinteger
cursorstring

Responses

200 List of teams

curl -X GET 'https://shoehorn.example.com/api/v1/teams' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/teams', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/teams',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/teams", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /teams/{id_or_slug} #

Get team by ID or slug (public)

Accepts either a UUID or a team slug.

Path parameters

id_or_slugstringrequired

Responses

200 Team details with members, mappings, and audit log

Schema (application/json)

TeamDetailsResponse
4properties
teamTeam
8properties
idstring<uuid>
namestring
slugstring
descriptionstring
metadataobject
parent_idstring<uuid>
created_atstring<date-time>
updated_atstring<date-time>
membersarray<TeamMember>
4properties
user_idstring
namestring
emailstring
rolestring
"lead""member""viewer"
group_mappingsarray<GroupMapping>
4properties
idstring<uuid>
group_namestring
providerstring
rolestring
audit_logarray<object>

curl -X GET 'https://shoehorn.example.com/api/v1/teams/{id_or_slug}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/teams/{id_or_slug}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/teams/{id_or_slug}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/teams/{id_or_slug}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Admin Teams

GET /admin/teams #

List all teams (admin)

Responses

200 All teams

curl -X GET 'https://shoehorn.example.com/api/v1/admin/teams' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/teams',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/teams", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /admin/teams #

Create team

Request body required

Content-Type: application/json

CreateTeamRequest

5properties

namestring*

slugstring

descriptionstring

parent_idstring

metadataobject

Responses

201 Team created

curl -X POST 'https://shoehorn.example.com/api/v1/admin/teams' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/teams',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/teams", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

GET /admin/teams/{id} #

Get team (admin)

Path parameters

idstringrequired

Responses

200 Team details

curl -X GET 'https://shoehorn.example.com/api/v1/admin/teams/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/teams/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

PUT /admin/teams/{id} #

Update team

Path parameters

idstringrequired

Request body required

Content-Type: application/json

UpdateTeamRequest

4properties

namestring

descriptionstring

parent_idstring

metadataobject

Responses

200 Team updated

curl -X PUT 'https://shoehorn.example.com/api/v1/admin/teams/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.put(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("PUT", "https://shoehorn.example.com/api/v1/admin/teams/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /admin/teams/{id} #

Delete team

Path parameters

idstringrequired

Responses

204 Team deleted

curl -X DELETE 'https://shoehorn.example.com/api/v1/admin/teams/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/admin/teams/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /admin/teams/{id}/members #

List team members

Path parameters

idstringrequired

Responses

200 Team members

curl -X GET 'https://shoehorn.example.com/api/v1/admin/teams/{id}/members' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}/members', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}/members',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/teams/{id}/members", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /admin/teams/{id}/members #

Add team member

Path parameters

idstringrequired

Request body required

Content-Type: application/json

object

2properties

user_idstring*

rolestring*

"lead""member""viewer"

Responses

201 Member added

curl -X POST 'https://shoehorn.example.com/api/v1/admin/teams/{id}/members' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}/members', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}/members',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/teams/{id}/members", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /admin/teams/{id}/members/{memberId} #

Remove team member

Path parameters

idstringrequired
memberIdstringrequired

Responses

204 Member removed

curl -X DELETE 'https://shoehorn.example.com/api/v1/admin/teams/{id}/members/{memberId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}/members/{memberId}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}/members/{memberId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/admin/teams/{id}/members/{memberId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /admin/teams/{id}/mappings #

List group mappings

Path parameters

idstringrequired

Responses

200 Group-to-team mappings

curl -X GET 'https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /admin/teams/{id}/mappings #

Add group mapping

Path parameters

idstringrequired

Request body required

Content-Type: application/json

object

3properties

group_namestring*

providerstring*

rolestring

"lead""member""viewer"

Responses

201 Mapping created

curl -X POST 'https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /admin/teams/{id}/mappings/{mappingId} #

Remove group mapping

Path parameters

idstringrequired
mappingIdstringrequired

Responses

204 Mapping removed

curl -X DELETE 'https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings/{mappingId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings/{mappingId}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings/{mappingId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/admin/teams/{id}/mappings/{mappingId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /admin/teams/{id}/roles #

Get team role assignments

Path parameters

idstringrequired

Responses

200 Roles assigned to team

curl -X GET 'https://shoehorn.example.com/api/v1/admin/teams/{id}/roles' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}/roles', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}/roles',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/admin/teams/{id}/roles", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

POST /admin/teams/{id}/roles #

Assign role to team

Path parameters

idstringrequired

Request body required

Content-Type: application/json

object

1property

role_idstring*

Responses

201 Role assigned

curl -X POST 'https://shoehorn.example.com/api/v1/admin/teams/{id}/roles' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}/roles', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests
r = requests.post(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}/roles',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
    json={},
)
data = r.json()

req, _ := http.NewRequest("POST", "https://shoehorn.example.com/api/v1/admin/teams/{id}/roles", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

DELETE /admin/teams/{id}/roles/{roleId} #

Remove role from team

Path parameters

idstringrequired
roleIdstringrequired

Responses

204 Role removed

curl -X DELETE 'https://shoehorn.example.com/api/v1/admin/teams/{id}/roles/{roleId}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/admin/teams/{id}/roles/{roleId}', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.delete(
    'https://shoehorn.example.com/api/v1/admin/teams/{id}/roles/{roleId}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("DELETE", "https://shoehorn.example.com/api/v1/admin/teams/{id}/roles/{roleId}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

Shoehorn Users API

v1.0.0

User directory and current-user profile. Group membership and role mappings are surfaced via the Groups API.

Base URL: https://shoehorn.example.com/api/v1

/

Users

GET /me #

Get current user profile

Returns the authenticated user's profile, team memberships, and group claims.

Responses

200 Current user profile

Schema (application/json)

object
8properties
idstring<uuid>
emailstring
namestring
picturestring
tenant_idstring
teamsarray<string>
Team slugs the user belongs to
groupsarray<string>
IdP group names from JWT claims
rolesarray<string>

curl -X GET 'https://shoehorn.example.com/api/v1/me' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/me', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/me',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/me", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /users #

List users

Returns all users in the tenant directory.

Query parameters

limitinteger
cursorstring
searchstring

Responses

200 User directory

Schema (application/json)

object
1property
usersarray<User>
6properties
idstring<uuid>
emailstring
namestring
picturestring
last_loginstring<date-time>
created_atstring<date-time>

curl -X GET 'https://shoehorn.example.com/api/v1/users' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/users', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/users',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/users", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)

GET /users/{id} #

Get user by ID

Returns a user's profile including group memberships and roles.

Path parameters

idstringrequired

Responses

200 User details

Schema (application/json)

UserDetail
10properties
idstring<uuid>
emailstring
namestring
picturestring
tenant_idstring
teamsarray<string>
groupsarray<string>
rolesarray<string>
last_loginstring<date-time>
created_atstring<date-time>
404 User not found

curl -X GET 'https://shoehorn.example.com/api/v1/users/{id}' \
  -H 'Authorization: Bearer $SHOEHORN_API_KEY'

const res = await fetch('https://shoehorn.example.com/api/v1/users/{id}', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SHOEHORN_API_KEY}`,
  },
});
const data = await res.json();

import os, requests
r = requests.get(
    'https://shoehorn.example.com/api/v1/users/{id}',
    headers={'Authorization': f'Bearer {os.environ["SHOEHORN_API_KEY"]}'},
)
data = r.json()

req, _ := http.NewRequest("GET", "https://shoehorn.example.com/api/v1/users/{id}", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOEHORN_API_KEY"))
res, err := http.DefaultClient.Do(req)