API reference

All API endpoints are available on every subdomain instance. Requests to the root domain operate on the “root” instance.

Instance management

/api/instance

Read, update, or delete the current subdomain instance's test state.

GETGet instance state. Add ?all=1 to list all instances.

Request

curl https://mysite.passfail.no/api/instance

Response

{
  "slug": "mysite",
  "failing": ["security-headers", "csp-deep-audit"],
  "createdAt": "2026-06-16T10:00:00",
  "updatedAt": "2026-06-16T10:30:00",
  "lastAccessedAt": "2026-06-16T11:00:00"
}

PATCHUpdate failing tests for the instance.

Request

curl -X PATCH https://mysite.passfail.no/api/instance \
  -H "Content-Type: application/json" \
  -d '{"failing": ["security-headers", "csp-deep-audit"]}'

Pass ?slug=mysite on the root domain to target a specific instance.

DELETEDelete the instance and its state.

Request

curl -X DELETE https://mysite.passfail.no/api/instance

Health check

/api/health

Configurable health endpoint for api-health-check and api-latency-benchmark tests.

GETReturns health status based on instance test state.

When api-health-check is failing: returns 503 with degraded service statuses. When api-latency-benchmark is failing: adds a 2-second delay.

Healthy response (200)

{
  "status": "healthy",
  "timestamp": "2026-06-16T10:00:00.000Z",
  "version": "0.1.0",
  "uptime": 86400,
  "services": {
    "database": { "status": "healthy", "latency": 2 },
    "cache": { "status": "healthy", "latency": 1 },
    "queue": { "status": "healthy", "latency": 5 }
  }
}

Degraded response (503)

{
  "status": "degraded",
  "timestamp": "2026-06-16T10:00:00.000Z",
  "services": {
    "database": { "status": "down", "latency": null, "error": "Connection refused" },
    "cache": { "status": "healthy", "latency": 3 },
    "queue": { "status": "degraded", "latency": 450, "error": "High queue depth" }
  }
}

GraphQL introspection

/api/graphql

Fixture GraphQL endpoint for testing introspection exposure.

POSTExecute a GraphQL query. Only introspection queries are handled.

When graphql-introspection is failing: returns the full mock schema (including sensitive fields like passwordHash, apiKey). When passing: returns 403 with “introspection disabled” error.

Request

curl -X POST https://mysite.passfail.no/api/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __schema { queryType { name } types { name fields { name } } } }"}'

Webhook receiver

/api/webhook-receiver

Configurable webhook endpoint for PullPush E2E testing. Supports 9 failure modes.

POSTReceive a webhook. Behavior controlled via ?mode= query parameter.

Mode	Behavior	Parameters
(none)	Accept and echo payload (200)	—
timeout	Hang for delay ms (default 30s)	delay
error	Return HTTP error status	status (400-599, default 500)
rate-limit	Return 429 with Retry-After	retry (seconds, default 60)
slow	Delay then respond 200	delay (ms, default 3000)
flaky	Random failure at given rate	rate (0-100, default 50)
bad-json	Return 200 with malformed JSON	—
empty	Return 200 with empty body	—
recover	Fail N times then succeed (stateful)	fail_count (default 5), status (default 503)

Examples

# Echo webhook
POST /api/webhook-receiver

# Simulate 503 error
POST /api/webhook-receiver?mode=error&status=503

# Rate limit with 30s retry
POST /api/webhook-receiver?mode=rate-limit&retry=30

# Fail 5 times then recover (stateful per instance)
POST /api/webhook-receiver?mode=recover&fail_count=5&status=503

# 30% random failure rate
POST /api/webhook-receiver?mode=flaky&rate=30

GETView webhook usage docs or delivery log.

View delivery log

# Recent deliveries (default limit 50)
GET /api/webhook-receiver?log=1

# Limit to 10
GET /api/webhook-receiver?log=1&limit=10

DELETEClear delivery log and reset recover counter.

Clear logs

DELETE /api/webhook-receiver

Contact form handler

/api/contact

Form submission handler for the contact-form test fixture.

POSTSubmit the contact form. Validates unless ?lax=1 is set.

Accepts both multipart/form-data and application/json. Includes honeypot detection (field: company_website).

Request

curl -X POST https://mysite.passfail.no/api/contact \
  -H "Content-Type: application/json" \
  -d '{"name": "Test User", "email": "test@example.com", "message": "Hello"}'