A Postman collection for testing n4n's chat completions API

A practical postman collection n4n chat completions setup cuts through the noise when you’re validating model responses, token metering, or fallback behavior against an OpenAI-compatible gateway. This tutorial builds a reusable collection from zero: environment variables, bearer auth, response assertions, and a request that exercises provider routing and cache-control forwarding. By the end you’ll have a file you can commit and run in CI with Newman.

Prerequisites

Postman 10+ (or Newman 5+ for headless runs)
A valid API key with per-token metering enabled
curl for side-by-side verification
Basic knowledge of the OpenAI chat completions request shape

If you haven’t pulled a key yet, do that first. The collection assumes the key sits in an environment variable, not hardcoded.

Environment setup

Create a Postman environment named n4n-env with three variables:

{
  "name": "n4n-env",
  "values": [
    { "key": "base_url", "value": "https://api.n4n.ai/v1", "enabled": true },
    { "key": "api_key", "value": "sk-...", "enabled": true },
    { "key": "default_model", "value": "openai/gpt-4o-mini", "enabled": true }
  ]
}

n4n.ai exposes an OpenAI-compatible endpoint at that base URL that fronts 240+ models and applies automatic fallback when a provider is rate-limited or degraded. Swap default_model to any qualified model ID later.

Collection skeleton with auth

Create a collection n4n-chat-tests. Set auth to Bearer Token using {{api_key}}. The exported minimal collection looks like:

{
  "info": {
    "name": "n4n-chat-tests",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_key}}", "type": "string" } ] },
  "item": []
}

Add requests under item. Postman inherits the collection auth, so individual calls stay clean.

Request: minimal chat completion

Add a request Basic Completion:

Method: POST
URL: {{base_url}}/chat/completions
Headers: Content-Type: application/json
Body (raw JSON):

{
  "model": "{{default_model}}",
  "messages": [
    { "role": "user", "content": "Return a JSON object with key 'ok' and value true." }
  ],
  "max_tokens": 60,
  "temperature": 0
}

Send it. Expected 200 response:

{
  "id": "chatcmpl-abc",
  "object": "chat.completion",
  "model": "openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "{\"ok\":true}" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 15, "completion_tokens": 8, "total_tokens": 23 }
}

The usage block reflects per-token metering on the gateway side; your local test just asserts it’s present.

Add response tests

In the request’s Tests tab, paste:

pm.test("status is 200", () => pm.response.to.have.status(200));
pm.test("has choices", () => {
  const body = pm.response.json();
  pm.expect(body.choices).to.be.an("array").with.length.greaterThan(0);
});
pm.test("usage metered", () => {
  const body = pm.response.json();
  pm.expect(body.usage.total_tokens).to.be.a("number").greaterThan(0);
});

Run the request. The test pane shows three green checks. This turns a manual probe into a regression guard.

Parameterize prompts and models

Hard-coding messages wastes the collection. Add a collection variable user_prompt and reference it:

{
  "model": "{{default_model}}",
  "messages": [ { "role": "user", "content": "{{user_prompt}}" } ],
  "max_tokens": 80
}

Now you can flip user_prompt per run or via Newman -d data file. For model coverage, duplicate the request and override model with anthropic/claude-3-5-sonnet to confirm cross-provider shape consistency.

Exercise routing and cache-control

The gateway honors client routing directives and forwards provider cache-control hints. To pin a provider and pass an Anthropic ephemeral cache hint, send a header x-n4n-route: anthropic and include the hint in the message:

{
  "model": "anthropic/claude-3-5-sonnet",
  "messages": [
    {
      "role": "system",
      "content": "You answer in one word.",
      "cache_control": { "type": "ephemeral" }
    },
    { "role": "user", "content": "{{user_prompt}}" }
  ],
  "max_tokens": 10
}

Set the header in Postman:

x-n4n-route: anthropic

Expected output mirrors the standard shape; the point is that the route header forces the upstream and the cache_control field rides through to Anthropic untouched. If the pinned provider is degraded, the gateway’s automatic fallback engages unless you disable it in the directive.

Streaming check (optional)

Postman’s UI doesn’t render SSE cleanly, but you can still validate the endpoint accepts stream:true using a pre-request script that switches to curl. Add a request Stream Probe with body:

{ "model": "{{default_model}}", "messages": [{"role":"user","content":"count 1 2 3"}], "stream": true }

In Tests, assert status 200 and Content-Type contains text/event-stream. For real inspection, run:

curl -N {{base_url}}/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"count 1 2 3"}],"stream":true}'

You’ll see data: {...} chunks. That confirms the postman collection n4n chat completions config is wired correctly even if the GUI lags.

Error handling and rate-limit simulation

A production gateway returns 401 or 429 with structured JSON. Add a request Bad Auth that uses a bogus key variable {{bad_key}} and test:

pm.test("401 on bad key", () => pm.response.to.have.status(401));

Similarly, send an oversized max_tokens to trigger validation errors and assert an error object exists. This hardens the postman collection n4n chat completions workflow against silent passthrough bugs.

Run in CI with Newman

Export the collection and environment. Run:

newman run n4n-chat-tests.json -e n4n-env.json --delay-request 200

Newman exits non-zero on test failure, making it a drop-in CI gate. For parallel model checks, loop over models with a small shell script and override default_model via --env-var.

for m in openai/gpt-4o-mini anthropic/claude-3-5-sonnet; do
  newman run n4n-chat-tests.json -e n4n-env.json --env-var default_model=$m || exit 1
done

Checklist before you commit

API key is in environment, not in collection JSON
Tests assert status, choices, and usage
Routing header only on requests that need provider pinning
Streaming verified via curl, not Postman UI
Error cases covered with negative tests

A tight postman collection n4n chat completions suite like this catches breaking changes in model IDs, auth errors, and missing usage fields long before your app users do.