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 ​

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.

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. 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, and Proxy and Composite endpoints pass through whatever the upstream service or the final step returns. SQL stored procedures are the freest of all: they shape their own payloads. The reference documents the success shape it can infer for each operation, so treat the error contract as universal and the success contract as per endpoint.

OData Query Parameters ​

SQL and Static endpoints support OData query parameters:

Rate Limiting ​

Rate-limited requests receive 429 Too Many Requests.

Health Endpoints ​

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