The Ngamia API repository ships a Postman collection organized by the same modules as this documentation: Authentication, Account, API Keys, Models, Gateway, Billing, Payments, Activity, and Notifications.
Files to import
| File | Use |
|---|---|
Ngamia-API.postman_collection.json | The requests and folders. Import this first. |
Ngamia-API.postman_environment.json | Local development variables with base_url = http://localhost:8080. |
Ngamia-API-Production.postman_environment.json | Production variables with base_url = https://api.ngamia.cc. |
Set up Postman
- In Postman, choose Import and add the collection JSON file.
- Import either the local or production environment JSON file.
- Select the environment from the top-right environment menu.
- Fill in the test email, phone, and password variables before running registration.
- Keep the active environment aligned with the API you intend to call.
Recommended first run
Run the requests in this order. Successful auth requests capture tokens into the active environment so later requests do not require manual copy and paste.
| Order | Request | What it does |
|---|---|---|
| 1 | Auth → Register | Creates a test account pending verification. |
| 2 | Auth → Verify OTP | Activates the account and captures access_token and refresh_token. |
| 3 | API Keys → Create API key | Creates an ngm_... key and captures its prefix and id. |
| 4 | Models → List models | Confirms which models are enabled for the key. |
| 5 | Gateway → Chat completions | Sends the first model request. |
| 6 | Billing → Get balance | Confirms the remaining credit balance. |
Local development may print the OTP to the server console when email or SMS credentials are not configured. Production requests require a working provider and an enabled, priced model.
Credential rules in the collection
| Collection area | Variable | Credential |
|---|---|---|
| Account, API keys, billing history, payments, activity, notifications | {{access_token}} | JWT access token |
| Models and Gateway | {{api_key}} | ngm_... API key |
| Chat completions and balance | Per-request | API key or JWT |
| Register, OTP, health checks, and gateway health | No auth | Public or operational request |
GET /v1/models is not public just because it is read-only; it requires an API key. Keep the environment file private if it contains captured tokens or keys.
Retry and response notes
The collection sends an idempotency key for top-ups and chat completions by default. Keep the same key when retrying one logical request, and generate a new key for a new operation.
Most JSON responses use the standard Ngamia envelope. Chat completions use the OpenAI response shape, and OAuth callbacks are browser redirects. See Errors and response format when a response does not match the expected shape.