API Reference

This is the map of Portway's API surface: routes, endpoint types, response codes, and the query parameters available to you. If you're integrating a client, this page and its siblings are where you'll find the contract.

All requests follow this URL pattern:

/api/{environment}/{endpoint}

The {environment} segment maps to a folder under environments/. The {endpoint} segment matches a configured endpoint name, or {namespace}/{endpoint} for namespaced endpoints.

Request flow ​

Endpoint types ​

Most endpoints live under a namespace, which becomes the first path segment:

Authentication ​

Include a bearer token on every request:

Authorization: Bearer your_token_here

Requests without a valid token return 401 Unauthorized. The only unauthenticated endpoint is /health/live. See Authentication for token scope configuration.

Response codes ​

Error format ​

Every endpoint type answers errors with the same small envelope, so you can handle failures the same way everywhere:

{
  "success": false,
  "error": "A human-readable message"
}

Validation failures (422) add a details array describing each problem:

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "Price", "message": "is required" }
  ]
}

In the API reference these appear as the shared ErrorResponse and ValidationErrorResponse schemas, which every operation references.

A 500 carries one extra field, traceId. The message itself stays deliberately vague, so this identifier is what ties your response back to the matching entry in the server log. It is worth quoting whenever you report a problem:

{
  "success": false,
  "error": "Error processing. Please check the logs for more details.",
  "traceId": "00-530e2d01e7e446f7c1a9936cd2858df4-77e01a3151145562-02"
}

Status codes by endpoint type ​

Every endpoint type shares the same error envelope, but each returns only the codes that make sense for it. This is the set you will see documented per operation in the API reference:

A 429 Too Many Requests can come back from any endpoint when a rate limit is exceeded. A 503 tells you the endpoint has been switched off through Enabled: false, and it arrives with a Retry-After header so you know how long to wait. 400 covers both a malformed request and an environment that is not on the allowed list; 403 means the token is valid but lacks the scope, or the target was blocked.

The success body, on the other hand, is specific to each endpoint:

• SQL queries return your rows
• Static endpoints return their configured content
• File downloads return bytes
• Proxy and Composite endpoints pass through whatever the upstream service or the final step returns
• SQL stored procedures are the freest of all, shaping their own payloads

The reference documents the success shape it can infer for each operation. In short, the error contract is universal and the success contract is per endpoint.

OData query parameters ​

SQL and Static endpoints accept $select, $filter, $orderby, $top, $skip and $count.

GET /api/prod/Products?$select=Name,Price&$filter=Price gt 100&$orderby=Name desc&$top=50

See OData syntax for the full option reference and Filter operations for the operator set.

Rate limiting ​

Requests are limited per IP and per token, and every response carries the X-RateLimit-* headers describing the applicable budget. Exceeding a limit returns 429 Too Many Requests with a Retry-After header.

Defaults, per-token overrides and Redis-backed buckets are covered in Rate limiting. The header set is listed in HTTP headers.

Health endpoints ​

/health/live is an unauthenticated liveness probe for load balancers. /health and /health/details require a token and report component status. See Health checks.

Next steps ​

• Authentication: token properties and scope patterns
• OData Syntax: filter, sort, and pagination
• Entity Configuration: endpoint configuration reference
• HTTP Headers: request and response headers