Postman & Insomnia collection

Prefer an API client to curl? Import the entire Phosra API into Postman or Insomnia in under a minute. The collection's structure is generated from the canonical OpenAPI 3.1 spec, with curated example bodies layered on top, and comes pre-wired to the hosted sandbox — every request already points at {{baseUrl}} and authenticates with a single {{apiKey}} variable. Import it, drop in your key, and press Send.

What's inside

The collection mirrors the API reference one-to-one:

Import into Postman

1. 1
   Download both files

   Grab the collection and the sandbox environment using the buttons above.

2. 2
   Import them

   In Postman, click Import (top-left) and drag both .json files in — or paste the file URLs into the Import → Link box. Postman detects the OpenAPI-derived collection and the environment automatically.

3. 3
   Select the environment

   In the environment dropdown (top-right), choose Phosra Sandbox. baseUrl is already set to the live sandbox.

4. 4
   Add your key (optional for public reads)

   Open the Phosra Sandbox environment, set apiKey to your phosra_test_… key, and save. Get one from Create your account. Public endpoints — Platforms, Ratings, Standards — return 200 without a key.

5. 5
   Send a request

   Open Platforms → List all platforms and press Send. You should get a 200 with the seeded platform catalog. You are now talking to the live sandbox.

Import into Insomnia

Insomnia reads Postman v2.1 collections natively:

1. 1
   Import the collection

   In Insomnia, open Application menu → Import, choose From File, and select phosra-api.postman_collection.json. Insomnia maps the 20 folders to request groups.

2. 2
   Set the base environment

   Open Manage Environments and add:

   json

   {
     "baseUrl": "https://phosra-api-sandbox-production.up.railway.app/api/v1",
     "apiKey": "phosra_test_your_key_here"
   }

   The imported requests already reference {{ baseUrl }} and {{ apiKey }}.

3. 3
   Send

   Pick any request and hit Send. Public reads work immediately; authenticated routes use your apiKey.

Verify it works

The first request most people run is Platforms → List all platforms. Resolved against the sandbox environment, it is exactly this call — copy-paste it to confirm the same 200 you'll see in Postman:

curl -s "https://phosra-api-sandbox-production.up.railway.app/api/v1/platforms"

Real response from the live sandbox (HTTP 200, ~220 ms), trimmed to the first entry:

[
  {
    "id": "fire_tablet",
    "name": "Amazon Fire Tablet",
    "category": "device",
    "tier": "pending",
    "enabled": true
  }
  // … 22 platforms total
]

That is the same endpoint, base URL, and response the collection produces on Send — no mocks, no key required.

Environment variables

Two variables control where you send and how you authenticate:

There is no supported two-variable move to production. Production access requires a separately scoped design-partner pilot, provisioned credentials, and operational review.

Resource IDs — defined, not left blank

Every path and body that needs an id (/families/:familyID, {"family_id": "…"}, and so on) reads from a named collection variable — never a hand-copied UUID buried in a URL. The collection ships with all of them defined, so nothing resolves to a dangling {{familyId}} on import:

Path ids on public reads are pre-bound to real sandbox values

A handful of requests take a fixed, keyless identifier in the URL rather than a captured variable — the public catalog reads (Platforms, Standards, Ratings, Providers). Instead of the generator's :platformID = "string" placeholder (which 404s on Send), every one of these is bound to a real value that resolves against the live sandbox immediately, no key and no setup:

Run it top to bottom — IDs chain themselves

The Create requests carry a Postman test script that saves the new resource's id straight into the collection variable the later requests read. Send them in order and you never paste a UUID:

1. 1
   Setup → One-step onboarding

   POST /setup/quick returns a family, child, policy, and starter rules in one call. Its test script sets familyId, childId, policyId, and ruleId for you.

2. 2
   Anything that reads them

   Get family, List children, Get policy, Create rule, Connect a webhook … all resolve against the ids the previous step captured. Create webhook / source / device / platform likewise write webhookId / sourceId / deviceId / linkId for their follow-up reads.

The capture scripts are plain pm.collectionVariables.set(...) calls — inspect them on any Create request under the Scripts → Post-response tab.

This full chain is proven against the live sandbox:

BASE=https://phosra-api-sandbox-production.up.railway.app/api/v1
 
# 1. One-step sandbox setup → synthetic family + child + policy ids
curl -s -X POST "$BASE/setup/quick" -H 'Content-Type: application/json' \
  -d '{"family_name":"Rivera Household","child_name":"Robin","birth_date":"2014-03-02"}'
# → 201 {"family":{"id":"a67a318c-…"},"child":{"id":"9a6782a2-…"},"policy":{"id":"ececceac-…"}, …}
 
# 2. GET the family the step above created (the id the test script captured)
curl -s "$BASE/families/a67a318c-f621-47a4-8ec9-e359db814b56"
# → 200 {"id":"a67a318c-…","name":"Rivera Household", …}
 
# standardId works with zero setup:
curl -s "$BASE/standards/four-norms"
# → 200 {"id":"33e8b8cf-1453-405a-8493-8fe76264623a","slug":"four-norms","name":"Four Norms", …}

Run in Postman

Keep it fresh

The collection's structure is derived from docs/api/openapi.yaml — the same spec that powers the reference and the inline Try it runner — so the endpoints, folders, and auth stay in lock-step with the live API. When the spec version bumps, re-download the checked-in files.

You can also regenerate the skeleton locally from the published spec (the CLI reads a local file, so fetch it first). Note the raw output ships schema-stub bodies ("name": "<string>"); the checked-in collection replaces those with the curated example bodies described above, so treat a fresh regen as a starting point, not a drop-in replacement:

curl -s https://phosra-api-sandbox-production.up.railway.app/openapi.json -o openapi.json
 
npx openapi-to-postmanv2 \
  -s openapi.json \
  -o phosra-api.postman_collection.json \
  -p -O folderStrategy=Tags

Next steps