API Overview

Shoehorn exposes a RESTful API at /api/v1/ for managing all platform resources programmatically.

Base URL

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

Authentication

All API requests must be authenticated using one of two methods:

Session Authentication (Browser)

Users authenticated via the web UI receive session cookies automatically. The frontend uses these cookies for API calls.

API Key Authentication (Programmatic)

For CI/CD pipelines and automation, use API keys:

curl -H "Authorization: Bearer shp_svc_xxxxxxxxxxxx" \
  https://shoehorn.example.com/api/v1/entities

API keys use the prefix shp_svc_ and are managed in Admin > API Keys.

See API Keys for key creation and scope details.

Request Format

• Content-Type: application/json for request bodies
• Accept: application/json for all responses
• Character Encoding: UTF-8

Response Format

Success Responses

Responses use top-level descriptive keys (no data wrapper):

Single resource:

{
  "id": "entity-123",
  "name": "my-service",
  "type": "service",
  "lifecycle": "production"
}

Collection with pagination:

{
  "entities": [
    { "id": "entity-123", "name": "my-service" }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "pageSize": 20,
    "nextCursor": "abc123"
  }
}

Error Responses

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Name is required",
    "details": {
      "field": "name",
      "reason": "required"
    }
  }
}

HTTP Status Codes

Code	Meaning
200 OK	Successful GET, PUT, PATCH
201 Created	Successful POST creating a resource
204 No Content	Successful DELETE
400 Bad Request	Malformed request
401 Unauthorized	Authentication required
403 Forbidden	Authenticated but insufficient permissions
404 Not Found	Resource not found
409 Conflict	Duplicate resource
422 Unprocessable Entity	Validation failed
500 Internal Server Error	Server error

Pagination

The API uses three pagination shapes depending on the endpoint:

Shape	Used By	Query Parameters	Key Response Fields
Cursor-based	Entities, Search, Forge, Deployments, Incidents, Zombies	limit, cursor	nextCursor, prevCursor, total
Page-based	Repositories	page, page_size	totalPages, totalItems, hasNext, hasPrevious
Identity Provider	Users	first/max or page/pageSize	count, hasMore, total

Example (cursor-based):

# First page
curl /api/v1/entities?limit=20

# Next page (use nextCursor from previous response)
curl /api/v1/entities?limit=20&cursor=20

Example (page-based):

curl /api/v1/repositories?page=1&page_size=20

See Pagination for complete details, response shapes, and per-endpoint reference.

Filtering

Many list endpoints support query parameter filters:

# Filter entities by type and lifecycle
curl /api/v1/entities?type=service&lifecycle=production

# Search entities
curl /api/v1/search?q=payment&type=service

Rate Limiting

API key requests are subject to rate limiting. The current limits are returned in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1706200000

Compression

The API supports gzip compression. Include the Accept-Encoding header:

curl -H "Accept-Encoding: gzip" /api/v1/entities

Request Size Limits

Endpoint	Default Limit
General API	1 MB
K8s agent push	10 MB
Manifest upload	5 MB

API Endpoints by Domain

Domain	Base Path	Spec File	Description
Entities	/api/v1/entities	entities.yaml	Entity CRUD, status, changelog, workloads, resources
Teams	/api/v1/teams, /api/v1/admin/teams	teams.yaml	Team management, members, group mappings
Users	/api/v1/users, /api/v1/me, /api/v1/groups	users.yaml	User directory, auth status, group role mappings
Kubernetes	/api/v1/k8s/agents	kubernetes.yaml	K8s agent registration, workload push, heartbeat
Governance	/api/v1/governance	governance.yaml	Governance actions and dashboard
Integrations	/api/v1/integrations	integrations.yaml	Integration CRUD, webhooks, sync
Admin	/api/v1/admin/*	admin.yaml	Settings, API keys, policies, features, scorecards
Catalog	/api/v1/search, /api/v1/stats, /api/v1/manifests	catalog.yaml	Search, statistics, manifest management
Operations	/api/v1/operations	operations.yaml	Workloads, deployments, GitOps, network flows
Metrics	/api/v1/metrics	metrics.yaml	Dashboard metrics and time-series
Organization	/api/v1/organization, /api/v1/admin/org-chart	organization.yaml	Org-chart read and bulk parent updates
Security	/api/v1/security	security.yaml	Security findings and overview
Forge	/api/v1/forge	forge.yaml	Workflow molds, runs, approvals
Marketplace	/api/v1/marketplace, /api/v1/addons	marketplace.yaml	Addon catalog, installation, runtime, logs
Notifications	/api/v1/notifications	notifications.yaml	User notifications and preferences

Health Endpoints

These endpoints do not require authentication:

# Liveness check
GET /healthz

# Database health
GET /healthz/db

# Readiness check
GET /readiness

OpenAPI Specs

Individual OpenAPI 3.0 specifications are available in specs/ organized by domain. Each file is self-contained and can be used with tools like Swagger UI or Postman.