Skip to main content

​
Overview

The Unleeshed Partner API uses API Key authentication for all server-to-server requests. API keys are issued to licensed partners and provide secure access to your licensed personas and commentary generation.

​
Getting Your API Key

  1. Log into the Partner Dashboard
  2. Navigate to Developer → API Keys
  3. Click Create API Key
  4. Select the required scopes (permissions)
  5. Copy and securely store the key
API keys are only shown once when created. Store them securely in your environment variables or secrets manager.

​
Using Your API Key

Include the API key in the X-Api-Key header for all requests: 
curl -X GET "https://api.unleeshed.ai/partner/v1/personas" \
  -H "X-Api-Key: pk_live_abc123..."

​
API Key Scopes

API keys have granular scopes that control what actions they can perform:
ScopeDescriptionEndpoints
personas:readView licensed personasGET /personas, GET /personas/:id
topics:submitCreate topics for commentaryPOST /topics
topics:readView topic status and resultsGET /topics, GET /topics/:id
usage:readView usage statisticsGET /usage
Follow the principle of least privilege. Only grant the scopes your integration actually needs.

​
Key Format

API keys follow this format: 
pk_[environment]_[random_string]

Examples:
- pk_live_abc123...  (Production)
- pk_test_xyz789...  (Sandbox/Testing)

​
Security Best Practices

API keys should only be used in server-side code. Never include them in:
  • JavaScript bundles served to browsers
  • Mobile app source code
  • Public repositories
  • Client-side environment variables
Store API keys in environment variables or a secrets manager:
# .env (never commit this file!)
UNLEESHED_API_KEY=pk_live_abc123...

// Access in your code
const apiKey = process.env.UNLEESHED_API_KEY;
Rotate your API keys every 90 days or immediately if you suspect compromise:
  1. Create a new API key in the dashboard
  2. Update your application to use the new key
  3. Verify the new key works
  4. Revoke the old key
For additional security, restrict your API key to specific IP addresses:
  1. Go to Developer → API Keys
  2. Click on your key
  3. Add allowed IP addresses
Requests from non-whitelisted IPs will be rejected.

​
Error Responses

Authentication errors return a 401 status code: 
{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}
Common authentication errors:
Error CodeDescriptionSolution
unauthorizedMissing or invalid API keyCheck that you’re including the X-Api-Key header
key_revokedAPI key has been revokedCreate a new API key in the dashboard
key_expiredAPI key has expiredCreate a new API key or contact support
ip_restrictedRequest from non-whitelisted IPAdd your IP to the allowed list
scope_deniedKey lacks required scopeCreate a new key with the needed scopes

​
Rate Limiting

API keys are subject to rate limits:
TierRate LimitBurst
Standard1,000 requests/hour100 requests/minute
Premium5,000 requests/hour500 requests/minute
When rate limited, you’ll receive a 429 response with a Retry-After header.

​
Next Steps

Create Your First Topic

Learn how to generate commentary with your API key.

API Reference

Explore all available endpoints.