Pagination & logs

Helicarrier endpoints use resource-specific response shapes. There is no universal data/next envelope. Use the cursor or sequence mechanism described for each operation.

Deployment history

GET /api/services/{id}/deployments returns the newest page first. The default limit is 25.

{
  "deployments": [],
  "nextCursor": 0
}

This is an illustrative empty response. With more results, take the returned nextCursor and send it as before on the next request:

curl --fail-with-body \
  'https://app.helicarrier.xyz/api/services/YOUR_SERVICE_ID/deployments?limit=25&before=CURSOR' \
  -H "Authorization: Bearer $HELI_API_KEY"

Stop when no next cursor is returned. The MCP list_deployments tool exposes limit, but does not currently expose REST’s before cursor.

Each deployment has a rollbackable field. Use it instead of assuming every historical release still has an image available for rollback.

Runtime logs

GET /api/services/{id}/logs returns { "logs": [...] }.

Query	Behavior
limit	Bound the number of lines
q	Substring search
before	Read older lines before a log ID
after	Read newer lines after a log ID, for incremental tailing
since	Inclusive RFC3339 timestamp
until	Exclusive RFC3339 timestamp

Historical reads can combine before, q, since, and until. When after is set, the handler uses the live-tail path; search and timestamp filters are not applied. Malformed time filters are ignored, so validate timestamps in your client.

curl --fail-with-body \
  'https://app.helicarrier.xyz/api/services/YOUR_SERVICE_ID/logs?limit=100&q=error' \
  -H "Authorization: Bearer $HELI_API_KEY"

The MCP get_logs tool exposes limit and q. Use REST for cursor and time-window controls.

Build and deployment logs

GET /api/deployments/{id}/logs returns a JSON array. Pass after with the last sequence number you processed to receive newer records. The MCP get_deployment_logs tool also exposes after.

curl --fail-with-body \
  'https://app.helicarrier.xyz/api/deployments/YOUR_DEPLOYMENT_ID/logs?after=0' \
  -H "Authorization: Bearer $HELI_API_KEY"

The deployment log stream is also available at GET /api/deployments/{id}/logs/stream for clients consuming server-sent events. Keep credentials in the Authorization header, not the URL. Browser-native EventSource cannot set arbitrary authorization headers; use a suitable server-side or fetch-based streaming client.

Metrics windows

For application metrics, GET /api/services/{id}/metrics?range=1h supports 1h, 6h, 24h, and 7d. The MCP get_metrics tool exposes the same range. Managed database metrics have a separate endpoint in the database reference.