---
title: Postman API Testing
description: How to use Postman for testing and debugging the Suno Studio API
---
import { Callout, Steps, Tabs } from 'nextra/components';
# Postman API Testing
Postman is our primary tool for testing, debugging, and documenting the Suno Studio API. We maintain an automatically-synced API collection that stays up-to-date with our codebase.
## What is Postman?
Postman is a collaborative API development platform that allows you to:
- **Test API endpoints** interactively without writing code
- **Debug requests and responses** with detailed inspection tools
- **Share API documentation** with team members
- **Organize endpoints** into logical collections
- **Manage environments** (local, staging, production)
- **Authenticate requests** using tokens and other auth methods
## How We Use Postman at Suno
### Automated API Collection
Our main API collection, **"Suno Studio API"**, is automatically generated from our OpenAPI schema:
The collection is automatically synced whenever `studio_api/schema.json` changes on the main branch. This ensures our Postman collection always reflects the latest API.
#### Sync Process
1. **Schema Generation**: When code changes are pushed, we generate an OpenAPI schema:
```bash
cd studio_api
uv run manage.py schema_codegen
```
2. **Automatic Sync**: A GitHub Action ([`sync-to-postman.yml`](https://github.com/suno-ai/glockenspiel/blob/main/.github/workflows/sync-to-postman.yml)) triggers on changes to `schema.json`:
- Converts OpenAPI spec to Postman collection format
- Reorganizes endpoints into logical folder hierarchies
- Updates the collection via Postman API
3. **Result**: Your Postman workspace automatically reflects the latest endpoints, parameters, and schemas.
**Important**: Any changes you make directly to the "Suno Studio API" collection will be overwritten on the next sync. If you want to customize endpoints, copy them to a separate collection first.
### Collections
**Primary Collection**: [Suno Studio API](https://sunoai.postman.co/workspace/Suno-Workspace~c31872ed-ff16-4aaa-858c-304ff913e6d3/collection/46782784-ac180881-a989-4b09-bdd6-15a8de7f87db)
- Full API spec generated from our Django Ninja endpoints
- Automatically updated with schema changes
- Read-only (modifications will be overwritten)
**Custom Collections**: Feel free to create your own collections by:
- Copying endpoints from the main collection
- Creating a personal workspace for experimentation
- Organizing endpoints for specific workflows
### Environments
Switch between environments using the dropdown in the top-right corner of Postman:
| Environment | Description | Use Case |
|------------|-------------|----------|
| **Local** | `localhost:8000` | Development on your machine |
| **Staging** | Staging server | Pre-production testing |
| **Prod** | Production server | Production debugging (careful!) |
## Getting Started
### Access the Workspace
Navigate to the [Suno Postman workspace](https://postman.com) (you'll need team access).
### Generate an Authentication Token
Authentication tokens are required for most API endpoints.
**For Local Development:**
1. Start your local server:
```bash
cd studio_api
uv run manage.py runserver
```
2. Open Django admin: [http://localhost:8000/margu/](http://localhost:8000/margu/)
3. Navigate to **"User Tokens"** → **"Add User Token"**
4. Create a token for your user (or use a pre-existing test token)
5. Copy the token value
**For Production:**
### Option 1: Quick Method
Use [this link](https://go.suno.com/hack) to grab your production token.
### Option 2: Using Jupyter Notebook
1. Use a Jupyter notebook connected to the production database
2. Query the Django ORM to create/retrieve a token:
```python
from studio_api.auth.models import UserToken
from django.contrib.auth.models import User
# Get or create user
user = User.objects.get(email='your.email@example.com')
# Create token
token = UserToken.objects.create(user=user)
print(token.key)
```
3. Copy the token value
### Configure Token in Postman
1. In Postman, click the **Environments** tab (or the environment dropdown in top-right)
2. Select your environment (e.g., "Local")
3. Find the `bearerToken` variable
4. Paste your token into the `bearerToken` variable
5. Save the environment
### Make Your First Request
1. Open the **Collections** tab
2. Navigate to "Suno Studio API"
3. Select an endpoint (e.g., `GET /users/me`)
4. Ensure the correct environment is selected (top-right dropdown)
5. Click **Send**
6. View the response below!
## Environment Variables
Each environment maintains its own set of variables. The key variables you'll work with:
| Variable | Description |
|----------|-------------|
| `baseUrl` | API base URL (e.g., `http://localhost:8000`, `https://api.staging.suno.ai`) |
| `bearerToken` | Authentication token for API requests |
| `Token` | Authentication token for API requests (deprecated, use `bearerToken` instead) |
You typically only need to update the token variables. The `baseUrl` is pre-configured for each environment.
## Best Practices
### DO ✅
- **Copy endpoints** to personal collections if you want to modify them
- **Use Local environment** for most development work
- **Document your custom collections** for team members
- **Save useful requests** for regression testing
### DON'T ❌
- **Edit the main "Suno Studio API" collection** (it will be overwritten)
- **Commit tokens** to version control
- **Share production tokens** via insecure channels
## Troubleshooting
### Authentication Errors (401)
**Problem**: Getting "Unauthorized" responses
**Solutions**:
1. Verify your token is correctly set in the environment variables
2. Check that the token is valid (not expired or deleted)
3. Ensure you're using the correct environment (Local vs Production)
4. Confirm the token has the necessary permissions for the endpoint
## Related Documentation
- [Backend Development Guide](/backend/backend-guide) - Studio API development guide
- [Studio API README](https://github.com/suno-ai/glockenspiel/blob/main/studio_api/README.md) - Full API documentation
- [Sync Workflow](https://github.com/suno-ai/glockenspiel/blob/main/.github/workflows/sync-to-postman.yml) - Automated sync implementation
## Technical Details
### Schema Generation
The OpenAPI schema is generated using Django Ninja's built-in schema generation:
```python
# studio_api/studio_api/bots/management/commands/schema_codegen.py
class Command(BaseCommand):
help = "Export Django Ninja OpenAPI schema"
def handle(self, *args, **options):
schema = main_api.get_openapi_schema()
# Outputs to schema.json
```
### Sync Workflow
The [sync-to-postman workflow](/.github/workflows/sync-to-postman.yml) runs on:
- Pushes to `main` branch that modify `studio_api/schema.json`
- Manual workflow dispatch
Conversion process:
```bash
# Install OpenAPI → Postman converter
npm i -g openapi-to-postmanv2
# Convert with optimizations
openapi2postmanv2 -s studio_api/schema.json -o collection.json -p \
-O folderStrategy=Paths,includeAuthInfoInExample=false,optimizeConversion=true
```
The workflow then:
1. Reorganizes flat paths into nested folders (e.g., `/users/auth` → `users > auth`)
2. Removes auth info from examples for security
3. Pushes to Postman via REST API
### Folder Restructuring
Endpoints are automatically organized hierarchically:
```
Before: /users/auth, /users/profile, /posts/create
After:
└── users
├── auth
└── profile
└── posts
└── create
```
This makes navigation in Postman much more intuitive!
---
**Questions or Issues?** Reach out in #engineering or check the [Studio API README](../../../../studio_api/README.md) for more details.