Pagination

The Shoehorn API uses three pagination shapes across different endpoint families. This page documents each shape, the endpoints that use it, and how to page through results.

Quick Reference

Endpoint	Shape	Query Parameters	Response Metadata Key
GET /entities	A - Cursor	limit, cursor	page
GET /search	A - Cursor	limit, cursor	page
GET /entities/{id}/deployments	A - Cursor	limit, cursor	pagination
GET /entities/{id}/incidents	A - Cursor	limit, cursor	pagination
GET /entities/zombies	A - Cursor	limit, cursor	page
GET /forge/molds	A - Cursor	limit, cursor	pagination
GET /forge/runs	A - Cursor	limit, cursor	pagination
GET /repositories	B - Page-based	page, page_size	pagination
GET /users	C - Identity Provider	first, max	page
GET /admin/users	C - Identity Provider	page, pageSize	page
GET /governance/actions	Limit/Offset	limit, offset	total (top-level)
GET /teams	Unpaginated	—	—

---

Shape A: Cursor-Based

Used by entity, search, forge, and several entity-detail endpoints. The cursor is an opaque string returned in the response; pass it back to fetch the next page.

Parameters

Parameter	Type	Default	Range	Description
limit	integer	20	1 — 100	Items per page
cursor	string	(none)	—	Opaque cursor from a previous response

Response Shapes

Endpoints in this group return the pagination metadata under either a page or pagination key (see the quick reference for which key each endpoint uses). The field names inside differ slightly depending on the endpoint family.

Entities, Search, Zombies — metadata key: page

{
  "entities": [ ... ],
  "page": {
    "limit": 20,
    "total": 150,
    "nextCursor": "20",
    "prevCursor": null
  }
}

Field	Type	Description
limit	integer	Requested page size
total	integer	Total matching items
nextCursor	string or null	Cursor for the next page (null on the last page)
prevCursor	string or null	Cursor for the previous page (null on the first page)

Search adds total and took at the top level alongside the page object:

{
  "results": [ ... ],
  "sections": { ... },
  "facets": { ... },
  "page": {
    "limit": 20,
    "offset": 0,
    "nextCursor": "20"
  },
  "total": 150,
  "took": "12ms"
}

Deployments, Incidents — metadata key: pagination

{
  "deployments": [ ... ],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 0,
    "nextCursor": "20",
    "prevCursor": null
  }
}

Forge Molds, Forge Runs — metadata key: pagination (snake_case fields)

{
  "runs": [ ... ],
  "pagination": {
    "total_count": 100,
    "next_cursor": "20",
    "has_more": false
  }
}

Field	Type	Description
total_count	integer	Total matching items
next_cursor	string	Cursor for the next page (empty string when done)
has_more	boolean	Whether more pages exist

Example

# First page
curl -H "Authorization: Bearer shp_svc_xxx" \
  "https://shoehorn.example.com/api/v1/entities?limit=20"

# Next page (use nextCursor from previous response)
curl -H "Authorization: Bearer shp_svc_xxx" \
  "https://shoehorn.example.com/api/v1/entities?limit=20&cursor=20"

Endpoints Using Shape A

Endpoint	Extra Filters
GET /entities	type, lifecycle, owner, team, tags, search, source, manifestType, hasRelations
GET /search	q (required), types, tags, owner, lifecycle
GET /entities/{id}/deployments	—
GET /entities/{id}/incidents	includeResolved
GET /entities/zombies	inactiveDays, minAge, lifecycle, type (limit max 200)
GET /forge/molds	visibility, category
GET /forge/runs	mold_slug, status

---

Shape B: Page-Based

Used by the repositories endpoint. Uses classic numbered pages with complete metadata for building page controls in the UI.

Parameters

Parameter	Type	Default	Range	Description
page	integer	1	1+	Page number (1-based)
page_size	integer	20	1 — 100	Items per page

Response Shape

{
  "repositories": [ ... ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 8,
    "totalItems": 150,
    "hasNext": true,
    "hasPrevious": false
  }
}

Field	Type	Description
page	integer	Current page number (1-based)
pageSize	integer	Actual page size
totalPages	integer	Total number of pages
totalItems	integer	Total matching items
hasNext	boolean	Whether a next page exists
hasPrevious	boolean	Whether a previous page exists

Example

# First page
curl -H "Authorization: Bearer shp_svc_xxx" \
  "https://shoehorn.example.com/api/v1/repositories?page=1&page_size=20"

# Page 3
curl -H "Authorization: Bearer shp_svc_xxx" \
  "https://shoehorn.example.com/api/v1/repositories?page=3&page_size=20"

Endpoints Using Shape B

Endpoint	Extra Filters
GET /repositories	search, provider, owner, language, topic, team, sort, order, show_forks, show_archived, show_private

---

Shape C: Identity Provider

Used by user directory endpoints. The parameter names (first/max) mirror the conventions of upstream identity providers (Zitadel, Okta).

Parameters

GET /users (public user directory):

Parameter	Type	Default	Range	Description
first	integer	0	0+	Offset (number of items to skip)
max	integer	100	1 — 200	Items per page
search	string	(none)	—	Search filter

GET /admin/users (admin user list):

Parameter	Type	Default	Range	Description
page	integer	0	0+	Page number (0-based)
pageSize	integer	100	1 — 200	Items per page
search	string	(none)	—	Search filter

Response Shape

{
  "items": [ ... ],
  "page": {
    "first": 0,
    "max": 100,
    "count": 50,
    "hasMore": true
  },
  "total": 250,
  "provider": "zitadel"
}

Field	Type	Description
page.first	integer	Offset used in this request
page.max	integer	Page size used in this request
page.count	integer	Number of items returned in this page
page.hasMore	boolean	Whether more items exist after this page
total	integer	Total users across all pages
provider	string	Identity provider name (e.g., zitadel, okta)

Example

# First page
curl -H "Authorization: Bearer shp_svc_xxx" \
  "https://shoehorn.example.com/api/v1/users?first=0&max=50"

# Next page
curl -H "Authorization: Bearer shp_svc_xxx" \
  "https://shoehorn.example.com/api/v1/users?first=50&max=50"

---

Limit/Offset Endpoints

Some endpoints use simple limit/offset parameters with a total count at the top level (no nested pagination object).

Parameters

Parameter	Type	Default	Range	Description
limit	integer	50	1 — 200	Items per page
offset	integer	0	0+	Number of items to skip

Response Shape

{
  "actions": [ ... ],
  "total": 150,
  "summary": {
    "open": 45,
    "in_progress": 20,
    "overdue": 5
  }
}

Endpoints

Endpoint	Extra Filters
GET /governance/actions	status, priority, entity_id, source_type, overdue

---

Unpaginated Endpoints

A few list endpoints return all items without pagination:

Endpoint	Notes
GET /teams	Returns all teams (cached 3 min per tenant)

---

General Notes

• Default limit: 20 for most endpoints, 50 for governance actions and zombies.
• Maximum limit: 100 for most endpoints, 200 for governance actions, zombies, and user endpoints.
• Cursor values are opaque: Treat cursor strings as opaque tokens. Do not parse, construct, or assume any internal format. Always use the value returned in the response.
• Empty pages: When no results match, endpoints return an empty array with the pagination metadata reflecting zero total items.
• Combining filters with pagination: Filters are applied before pagination. Changing a filter resets the result set, so start from the first page (no cursor / page 1).