API Design

Header Policies

Header policies keep response headers consistent across your APIs. A policy bundles one or more reusable header components — say, rate-limit headers — and automatically applies them to every response whose status code matches the policy's scopes. Policies cascade from the organization down to projects and individual specifications, so you define a standard once and every API inherits it.

Policies and header components

Two building blocks work together:

Concept What it is
Header component A reusable definition of a single HTTP header: name (e.g. X-Rate-Limit), schema type (String, Integer, Number, or Boolean), required flag, and description. Header components can also be attached to responses directly, independent of any policy.
Header policy A governance rule that automatically applies a set of header components to all responses matching its status-code scopes. Policies can be enabled/disabled, are priority-ordered, and support per-response exclusions.

Where policies live

Policies exist at three cascade levels — Organization → Project → Specification — and the most specific level wins where they overlap.

  • Organization-wide policies are managed under Settings → API Header Policies: "Define organization-wide header policies that apply to all API specifications across all projects." Managing them requires the org:manage-governance permission (Admins and Owners); Members see them read-only.
  • Project- and specification-level settings show the same two cards — Header Policies and Header Components — scoped to that level.

Each Header Policies card lists the policies with a status icon, scope and header count badges, an enable toggle, and edit/delete actions. Drag the handle to reorder policies — order determines priority, and the lower-priority policy yields when two policies overlap.

The API Header Policies settings page with the policy list and header components card

Creating a policy

  1. Click Create Policy.
  2. In the Create Header Policy dialog — "Define a policy to automatically apply headers to responses matching specific status codes." — enter:
    • Name (required) — a descriptive name, e.g. Rate Limiting Headers.
    • Description (optional) — when and why this policy applies.
    • Scopes — which responses the policy targets. Add at least one scope.
    • Header Components — pick the headers to apply via the Select headers... multi-select.
  3. Save. A toast confirms the policy was created.

Scopes

Scopes are status-code based. Quick-add buttons cover All status codes and the 2xx, 3xx, 4xx, and 5xx classes; you can also add an exact code (e.g. 429, valid range 100–599). For endpoint-specific opt-outs, use exclusions instead of narrowing the policy.

Enabling and disabling

Every policy has an Enabled toggle with badges showing its state. When disabled, the policy stops applying headers to any responses — useful for staging a policy before rolling it out.

Creating header components

On the Header Components card ("Reusable header definitions available to all policies" at that level):

  • Add Component opens the Create Header Component dialog: Name (e.g. X-Rate-Limit), Schema Type (String / Integer / Number / Boolean), a Required checkbox, and an optional Description.
  • Add Common Headers offers 14 pre-built standard headers — Authorization, Content-Type, Accept, X-Request-Id, X-Correlation-Id, Cache-Control, X-Rate-Limit-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Reset, X-API-Version, Accept-Language, If-None-Match, ETag, and Retry-After — with headers that already exist shown as disabled. Select what you need and click Add Selected.

Header components are inheritable the same way policies are (organization → project → specification). In the API Designer you can also attach a header component to a response directly, either through the header multi-select or by dragging it onto a response.

Impact analysis

When editing a policy, the Impact Analysis card shows exactly what it touches:

  • A summary — "This policy applies to N endpoint(s) across M response(s)." — with badges for affected endpoint and conflict counts.
  • Conflict warnings when the policy overlaps another (e.g. "Overlaps with {policy} on {scopes}"), including the priority that decides the winner.
  • A row per affected endpoint with its method, path, matching status codes, markers for local overrides and exclusions, and a jump-to-endpoint shortcut.

If nothing matches yet, the panel explains: "This policy has no matching endpoints. Add scopes and enable the policy to see affected endpoints."

Header inheritance in the API Designer

Inside a specification, the collapsible Header Inheritance section in the sidebar shows every policy affecting the spec, grouped by level (Org / Project / Specification) with an active-policy count. Each entry shows the policy's enabled state, name, and header count; hovering reveals its description and header list, and a link takes you to Manage policies at the right level.

Excluding a header on a single response

Sometimes one response legitimately shouldn't carry an inherited header. Open the response and exclude the header: the Exclude Header dialog explains — "This will exclude the header {header} inherited from policy {policy} for this response only." — and offers an optional Reason field to document why. Exclusions require write access to the spec (specs:write) and only affect that one response; the policy stays intact everywhere else.