REST API

REST API Reference

Direct HTTP access to the Wayforth gateway. All endpoints accept JSON and return JSON. The SDK is a thin wrapper around these endpoints.

Base URL

http

https://gateway.wayforth.io

All paths are versioned under /v1/. The gateway runs on Railway with auto-scaling and a global CDN edge layer.

Authentication

Pass your API key in the x-wayforth-api-key header on every request:

bash

curl https://gateway.wayforth.io/v1/balance \
  -H "x-wayforth-api-key: wf_live_your_key_here"

Key prefix	Scope	Charges credits
`wf_live_`	Production — all endpoints	Yes
`wf_test_`	Testing — responses are mocked	No

Rate limiting: 10 consecutive failed authentication attempts from the same IP within 60 seconds will result in a 429 too_many_auth_failures response. Use test keys during development to avoid this.

Endpoint overview

Method	Path	Description
POST	`/v1/search`	Natural language service search
POST	`/v1/query`	WayforthQL structured search
POST	`/v1/execute/{slug}`	Execute a managed service
POST	`/v1/run`	Search + execute in one call
GET	`/v1/balance`	Account credits and usage
GET	`/v1/services`	Browse service catalog
GET	`/billing/balance`	Detailed billing balance
POST	`/billing/upgrade`	Upgrade subscription tier
POST	`/billing/topup`	Purchase top-up credits
GET	`/billing/packages`	Available plans and top-up packages
GET	`/health`	Gateway health check (no auth)

POST /v1/search

Natural language search ranked by semantic relevance × WRI score.

Request body

json

{
  "query": "translate text to Spanish",
  "tier": 2,
  "max_price_usd": 0.01,
  "max_latency_ms": 2000,
  "region": "us-east",
  "payment_rail": "card",
  "limit": 10
}

Response

json

[
  {
    "slug": "deepl",
    "name": "DeepL Translation",
    "description": "Neural machine translation in 31 languages",
    "wri_score": 94,
    "tier": 2,
    "category": "translation",
    "payment_rails": ["card", "usdc", "x402"],
    "price_per_call": 0.003,
    "region": "eu-west"
  }
]

bash

curl -X POST https://gateway.wayforth.io/v1/search \
  -H "x-wayforth-api-key: $WAYFORTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "translate to Spanish", "tier": 2}'

POST /v1/query

WayforthQL structured query. See WayforthQL v1.1 for syntax.

bash

curl -X POST https://gateway.wayforth.io/v1/query \
  -H "x-wayforth-api-key: $WAYFORTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ql": "category:vision AND tier:>=3 SORT BY wri_score DESC LIMIT 5"}'

Request body

ql string WayforthQL query string. required

POST /v1/execute/{slug}

Execute a managed service. The request body is passed directly to the upstream service as its native parameters.

bash

curl -X POST https://gateway.wayforth.io/v1/execute/deepl \
  -H "x-wayforth-api-key: $WAYFORTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, world!", "target_lang": "ES"}'

json

{
  "translation": "¡Hola, mundo!",
  "detected_source_lang": "EN",
  "billed_calls": 1,
  "credits_remaining": 846,
  "latency_ms": 318,
  "provider": "deepl"
}

Path parameters

slug string Service slug from /v1/search or /v1/services. required

POST /v1/run

Find the best service for a natural language query and execute it in one call.

bash

curl -X POST https://gateway.wayforth.io/v1/run \
  -H "x-wayforth-api-key: $WAYFORTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "translate Hello to Spanish"}'

json

{
  "output": "Hola",
  "service": "deepl",
  "wri_score": 94,
  "billed_calls": 1,
  "credits_remaining": 845
}

GET /v1/balance

Returns current credits, tier, and usage forecast.

bash

curl https://gateway.wayforth.io/v1/balance \
  -H "x-wayforth-api-key: $WAYFORTH_API_KEY"

json

{
  "credits_remaining": 847,
  "tier": "builder",
  "usage": {
    "calls_this_period": 153,
    "calls_included": 1000
  }
}

GET /v1/services

Browse the full service catalog. Filter by category with the category query parameter.

bash

# All services
curl "https://gateway.wayforth.io/v1/services" \
  -H "x-wayforth-api-key: $WAYFORTH_API_KEY"

# Filter by category
curl "https://gateway.wayforth.io/v1/services?category=audio" \
  -H "x-wayforth-api-key: $WAYFORTH_API_KEY"

Billing endpoints

GET /billing/balance

Extended balance with full billing period details and usage forecast.

json

{
  "calls_remaining": 847,
  "calls_included": 1000,
  "billing_period_start": "2026-05-01T00:00:00Z",
  "next_reset": "2026-06-01T00:00:00Z",
  "days_until_reset": 15,
  "plan": "builder",
  "forecast": {
    "daily_avg_calls": 10,
    "days_remaining_at_current_rate": 84,
    "projected_reset_balance": 697,
    "will_exhaust_before_reset": false
  }
}

POST /billing/upgrade

Create a Stripe Checkout session to upgrade your plan.

json

// Request
{ "target_tier": "pro" }

// Response
{ "checkout_url": "https://checkout.stripe.com/c/pay/..." }

Valid tiers: builder, starter, pro, growth. Cannot downgrade via API — contact support.

POST /billing/topup

Create a Stripe Checkout session for a top-up package.

json

// Request
{ "package": "large" }

// Response
{ "checkout_url": "https://checkout.stripe.com/c/pay/..." }

Valid packages: small ($5/500), medium ($10/1100), large ($25/3000), xl ($50/7000).

GET /billing/packages

Returns available upgrade tiers and top-up packages for the current user.

GET /billing/invoice/{year}/{month}

Returns a monthly invoice. Example: /billing/invoice/2026/05.

Rate limits

Rate limits apply to all endpoints. Limits are per API key, not per IP.

Tier	Requests / minute	Calls / month
free	10	100
builder	60	1,000
starter	120	3,500
pro	300	12,000
growth	600	40,000

Rate limit headers

Every response includes rate limit context:

http

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1748012400
X-Credits-Remaining: 847

When the rate limit is exceeded, the gateway returns 429 Too Many Requests with a Retry-After header indicating seconds to wait.

Error codes

All errors follow the same JSON envelope with a detail field:

json

{
  "detail": "Insufficient credits. Top up at https://wayforth.io/billing",
  "error_code": "insufficient_credits",
  "credits_remaining": 0
}

Status	error_code	Description
200	–	Success
400	`bad_request`	Invalid JSON or missing required field
401	`invalid_api_key`	Missing or invalid `x-wayforth-api-key` header
402	`insufficient_credits`	Account has 0 credits remaining
404	`service_not_found`	Slug does not exist in the catalog
422	`validation_error`	Request body fails schema validation
429	`rate_limit_exceeded`	Too many requests — check `Retry-After` header
429	`too_many_auth_failures`	10+ consecutive auth failures from this IP in 60s
500	`internal_error`	Unexpected gateway error
503	`service_unavailable`	Upstream provider unavailable, failover exhausted

Health check

The /health endpoint requires no authentication and is safe to poll:

bash

curl https://gateway.wayforth.io/health

json

{
  "status": "ok",
  "service": "wayforth-gateway",
  "version": "0.7.0"
}

Webhook events: Subscribe to gateway events (balance warnings, service degradation, payment failures) at wayforth.io/settings/webhooks. Full event list available at GET /webhooks/events.