The SitePulse API uses consistent JSON formatting, standard HTTP status codes, and Laravel pagination conventions.
Content type All requests and responses use JSON:
Request bodies: application/jsonResponses: application/json
Resource wrapping Single resources Single resources are wrapped in a data key:
{ "data" : { "uuid" : "..." , "name" : "Example" } }
Some endpoints (for example GET /me) nest multiple objects inside data:
{ "data" : { "user" : { "id" : 1 , "name" : "..." , "email" : "..." }, "teams" : [ ... ] } }
Collections Collections use Laravel’s paginator format:
{ "data" : [ ... ], "links" : { "first" : "..." , "last" : "..." , "prev" : null , "next" : "..." }, "meta" : { "current_page" : 1 , "from" : 1 , "last_page" : 3 , "path" : "..." , "per_page" : 25 , "to" : 25 , "total" : 62 } }
Non-paginated collections (for example GET /teams) return data as an array without links / meta.
Timestamps All datetime fields are ISO 8601 strings in UTC:
2026-05-28T14:32:10+00:00
Identifiers Different resources use different identifier types:
Resource Route key Format Example path Team Numeric id Integer /teams/1Site uuidUUID string /sites/{uuid}Check uuidUUID string /checks/{uuid}Issue uuidUUID string /issues/{uuid}User Numeric id Integer Appears on nested user objects
Team context For routes under a team, site, check, or issue, middleware resolves the team and sets it as the token user’s current team for that request. This drives plan-limit checks and policies that depend on currentTeam.
You do not send a separate X-Team-Id header. Scope operations with the team id or site uuid in the path.
For GET /issues, filter to one team with ?team={team_id}. Without team, results include all teams where the user has viewIssues permission.
List endpoints accept these query parameters:
Query Type Default Max pageinteger ≥ 1 1— per_pageinteger 25100
Example cURL
JavaScript
Python
Go
Ruby
PHP
curl -sS \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" \ "https://app.sitepulse.dev/api/v1/teams/1/sites?page=2&per_page=50"
HTTP status codes Code Meaning 200Success 201Created (site) 202Accepted (check run queued) 204Success, no body (delete) 401Missing or invalid token 402Team subscription inactive 403Missing scope or team permission 404Resource not found or not in your teams 422Validation error 429Rate limit exceeded
Validation errors (422) Laravel’s standard validation shape:
{ "message" : "The url field is required. (and 1 more error)" , "errors" : { "url" : [ "The url field is required." ] } }
Common validation cases
Duplicate site URL within a team
Plan site limit reached
Check tool not allowed on plan or not enabled on site
Invalid cadence for plan tier
Invalid filter or sort query parameters
Authorization vs not found Cross-team access to sites, checks, and issues returns 404 Not Found rather than 403, so resource existence is not leaked across tenants.
Rate limits All API routes use the default api throttle middleware.
Check runs are further limited:
POST /sites/{site}/checks — 10 requests per minute per token/user
When throttled, the API returns 429 Too Many Requests with Retry-After headers where configured.
Enums Tool values in request bodies and responses:
Value Check statusHTTP uptime sslTLS certificate dnsDNS records broken-linksCrawl broken links performanceLighthouse performance
Check status Value Description pendingQueued or running completedFinished successfully failedFinished with error skippedNot run (for example plan or config)
Issue status Value Description openActive incident acknowledgedAcknowledged by a team member resolvedProblem has cleared
Filter with status=active to include both open and acknowledged issues.
The API supports read access only. Acknowledge and resolve actions are available in the dashboard Issues page.
Issue severity Example requests cURL
JavaScript
Python
Go
Ruby
PHP
# GET request curl -sS \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" \ "https://app.sitepulse.dev/api/v1/teams/1/sites" # POST request curl -sS -X POST \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com","name":"Example"}' \ "https://app.sitepulse.dev/api/v1/teams/1/sites" # DELETE request curl -sS -X DELETE \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" \ "https://app.sitepulse.dev/api/v1/sites/{uuid}"
See also 
