Spending Limits & Permissions — Hypery Docs

Overview

The spending limits API allows administrators to:

Set permission modes (allowlist/denylist/unrestricted)
Configure spending limits by provider, author, or specific model
Override limits for individual users
Track usage against configured limits

Permission Modes

Mode	Behavior	Use Case
`allowlist`	Only explicitly allowed items are accessible	Maximum security and cost control
`denylist`	Everything except denied items is accessible	Flexible with specific exclusions
`unrestricted`	All models and providers accessible	Open access (use with caution)

Team Model Permissions

Get Team Permissions

Endpoint: GET /api/teams/{teamId}/model-permissions

const response = await fetch('https://hypery.ai/api/teams/{teamId}/model-permissions', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});
 
const permissions = await response.json();

import requests
 
response = requests.get(
    'https://hypery.ai/api/teams/{teamId}/model-permissions',
    headers={'Authorization': f'Bearer {api_key}'}
)
 
permissions = response.json()

curl https://hypery.ai/api/teams/TEAM_ID/model-permissions \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "mode": "allowlist",
  "allowedProviders": ["openrouter", "replicate"],
  "deniedProviders": [],
  "allowedAuthors": ["anthropic", "openai", "google"],
  "deniedAuthors": [],
  "allowedModels": ["anthropic/claude-3.5-sonnet:openrouter"],
  "deniedModels": ["openai/o1:openrouter"],
  "providerLimits": {
    "openrouter": {
      "dailyCredits": 5000,
      "monthlyCredits": 100000
    }
  },
  "authorLimits": {
    "anthropic": {
      "dailyCredits": 2000,
      "monthlyCredits": 40000
    }
  },
  "modelLimits": {
    "openai/gpt-4o:openrouter": {
      "dailyCredits": 1000,
      "monthlyCredits": 10000
    }
  }
}

Update Team Permissions

Endpoint: PATCH /api/teams/{teamId}/model-permissions

const response = await fetch('https://hypery.ai/api/teams/{teamId}/model-permissions', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mode: 'allowlist',
    allowedProviders: ['openrouter'],
    allowedAuthors: ['anthropic', 'openai'],
    providerLimits: {
      openrouter: {
        dailyCredits: 5000,
        monthlyCredits: 100000
      }
    }
  })
});
 
const result = await response.json();

import requests
 
response = requests.patch(
    'https://hypery.ai/api/teams/{teamId}/model-permissions',
    headers={'Authorization': f'Bearer {api_key}'},
    json={
        'mode': 'allowlist',
        'allowedProviders': ['openrouter'],
        'allowedAuthors': ['anthropic', 'openai'],
        'providerLimits': {
            'openrouter': {
                'dailyCredits': 5000,
                'monthlyCredits': 100000
            }
        }
    }
)
 
result = response.json()

curl -X PATCH https://hypery.ai/api/teams/TEAM_ID/model-permissions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "allowlist",
    "allowedProviders": ["openrouter"],
    "allowedAuthors": ["anthropic", "openai"],
    "providerLimits": {
      "openrouter": {
        "dailyCredits": 5000,
        "monthlyCredits": 100000
      }
    }
  }'

Input Parameters:

Parameter	Type	Required	Description
`mode`	string	Yes	Permission mode: `allowlist`, `denylist`, or `unrestricted`
`allowedProviders`	string[]	No	Providers allowed (if allowlist mode)
`deniedProviders`	string[]	No	Providers denied (if denylist mode)
`allowedAuthors`	string[]	No	Model authors allowed (e.g., "anthropic", "openai")
`deniedAuthors`	string[]	No	Model authors denied
`allowedModels`	string[]	No	Specific models allowed (format: "modelId:provider")
`deniedModels`	string[]	No	Specific models denied
`providerLimits`	object	No	Spending limits per provider
`authorLimits`	object	No	Spending limits per author
`modelLimits`	object	No	Spending limits per model

Spending Limit Object:

{
  "dailyCredits": 5000,      // Credits per day (-1 for unlimited)
  "monthlyCredits": 100000   // Credits per month (-1 for unlimited)
}

Response:

{
  "success": true,
  "message": "Team model permissions updated successfully",
  "permissions": { /* updated permissions object */ }
}

Permissions Required: Team Owner or Admin

User-Specific Permissions

Get User Permissions

Endpoint: GET /api/teams/{teamId}/users/{userId}/model-permissions

const response = await fetch(
  `https://hypery.ai/api/teams/${teamId}/users/${userId}/model-permissions`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
const userPermissions = await response.json();

import requests
 
response = requests.get(
    f'https://hypery.ai/api/teams/{team_id}/users/{user_id}/model-permissions',
    headers={'Authorization': f'Bearer {api_key}'}
)
 
user_permissions = response.json()

curl https://hypery.ai/api/teams/TEAM_ID/users/USER_ID/model-permissions \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "hasOverrides": true,
  "permissions": {
    "mode": "allowlist",
    "allowedModels": ["openai/o1:openrouter"],
    "modelLimits": {
      "openai/o1:openrouter": {
        "dailyCredits": 1000,
        "monthlyCredits": 10000
      }
    }
  },
  "reason": "Senior engineer - approved for premium models",
  "setBy": "507f1f77bcf86cd799439011",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Set User Permissions

Endpoint: PUT /api/teams/{teamId}/users/{userId}/model-permissions

const response = await fetch(
  `https://hypery.ai/api/teams/${teamId}/users/${userId}/model-permissions`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      permissions: {
        mode: 'allowlist',
        allowedModels: ['openai/o1:openrouter'],
        modelLimits: {
          'openai/o1:openrouter': {
            dailyCredits: 1000,
            monthlyCredits: 10000
          }
        }
      },
      reason: 'Senior engineer - needs advanced reasoning models'
    })
  }
);
 
const result = await response.json();

import requests
 
response = requests.put(
    f'https://hypery.ai/api/teams/{team_id}/users/{user_id}/model-permissions',
    headers={'Authorization': f'Bearer {api_key}'},
    json={
        'permissions': {
            'mode': 'allowlist',
            'allowedModels': ['openai/o1:openrouter'],
            'modelLimits': {
                'openai/o1:openrouter': {
                    'dailyCredits': 1000,
                    'monthlyCredits': 10000
                }
            }
        },
        'reason': 'Senior engineer - needs advanced reasoning models'
    }
)
 
result = response.json()

curl -X PUT https://hypery.ai/api/teams/TEAM_ID/users/USER_ID/model-permissions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "mode": "allowlist",
      "allowedModels": ["openai/o1:openrouter"],
      "modelLimits": {
        "openai/o1:openrouter": {
          "dailyCredits": 1000,
          "monthlyCredits": 10000
        }
      }
    },
    "reason": "Senior engineer - needs advanced reasoning models"
  }'

Input Parameters:

Parameter	Type	Required	Description
`permissions`	object	Yes	User-specific permission overrides
`reason`	string	No	Explanation for custom permissions (recommended for audit trail)

Response:

{
  "success": true,
  "message": "User model permissions updated successfully",
  "permissions": { /* updated permissions */ },
  "reason": "Senior engineer - needs advanced reasoning models"
}

Remove User Permissions

Revert user to team defaults by removing custom permissions.

Endpoint: DELETE /api/teams/{teamId}/users/{userId}/model-permissions

const response = await fetch(
  `https://hypery.ai/api/teams/${teamId}/users/${userId}/model-permissions`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);
 
const result = await response.json();

import requests
 
response = requests.delete(
    f'https://hypery.ai/api/teams/{team_id}/users/{user_id}/model-permissions',
    headers={'Authorization': f'Bearer {api_key}'}
)
 
result = response.json()

curl -X DELETE https://hypery.ai/api/teams/TEAM_ID/users/USER_ID/model-permissions \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "message": "User permissions removed. User will now use team defaults."
}

Authorized App Permissions

Update App Permissions

Modify which permissions an authorized app has access to.

curl -X PATCH https://your-gateway.com/api/user/authorized-apps/{appId}/permissions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["read", "ai:chat", "ai:models"]
  }'

const response = await fetch(
  'https://your-gateway.com/api/user/authorized-apps/{appId}/permissions',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      scopes: ['read', 'ai:chat', 'ai:models']
    })
  }
);
 
const result = await response.json();

import requests
 
response = requests.patch(
    'https://your-gateway.com/api/user/authorized-apps/{appId}/permissions',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'scopes': ['read', 'ai:chat', 'ai:models']}
)
 
result = response.json()

Input Parameters:

Parameter	Type	Required	Description
`scopes`	string[]	Yes	Array of permission scopes (cannot be empty)

Response:

{
  "success": true,
  "scopes": ["read", "ai:chat", "ai:models"]
}

Error Response (400):

{
  "error": "Cannot remove all permissions. Please revoke access instead."
}

Revoke App Access

Completely revoke an app's access to your account.

curl -X POST https://your-gateway.com/api/user/authorized-apps/{appId}/revoke \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://your-gateway.com/api/user/authorized-apps/{appId}/revoke',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
 
const result = await response.json();

import requests
 
response = requests.post(
    'https://your-gateway.com/api/user/authorized-apps/{appId}/revoke',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
 
result = response.json()

Response:

{
  "success": true,
  "message": "Access revoked successfully"
}

Pricing Tiers

Models are automatically categorized into pricing tiers for easier filtering and cost control:

Tier	Cost Range	Examples
Free	Exactly $0	Free OpenRouter models
Budget	$0.01 - $0.99 per 1M tokens	Claude Haiku, GPT-4o-mini
Standard	$1 - $9.99 per 1M tokens	GPT-4o, Claude Sonnet
Premium	$10+ per 1M tokens	Claude Opus, OpenAI o1

Cost is calculated as the average of input and output token costs for token-based models, with equivalent conversions for generation/time-based models.

Permission Hierarchy

Limits are applied in order from most specific to least specific:

User-specific model limits (highest priority)
User-specific author limits
User-specific provider limits
Team model limits
Team author limits
Team provider limits
System defaults (lowest priority)

The most restrictive limit always wins. For example, if a user has a 2000/day limit but the team has a 1000/day limit for a specific model, the 1000/day limit applies.

Use Cases

Block Expensive Models Team-Wide

PATCH /api/teams/{teamId}/model-permissions
{
  "mode": "denylist",
  "deniedModels": [
    "openai/o1:openrouter",
    "anthropic/claude-opus-4:openrouter"
  ]
}

Allow Only Specific Providers

PATCH /api/teams/{teamId}/model-permissions
{
  "mode": "allowlist",
  "allowedProviders": ["openrouter"],
  "providerLimits": {
    "openrouter": {
      "dailyCredits": 10000,
      "monthlyCredits": 200000
    }
  }
}

Grant Premium Model Access to Specific User

PUT /api/teams/{teamId}/users/{userId}/model-permissions
{
  "permissions": {
    "mode": "allowlist",
    "allowedModels": ["openai/o1:openrouter"],
    "modelLimits": {
      "openai/o1:openrouter": {
        "dailyCredits": 1000,
        "monthlyCredits": 10000
      }
    }
  },
  "reason": "Senior engineer - research project"
}

Error Codes

Code	Status	Description
`Unauthorized`	401	Missing or invalid API key
`Forbidden`	403	User is not a team admin
`Not Found`	404	Team or user not found
`Bad Request`	400	Invalid permission structure or empty scopes
`Internal Server Error`	500	Server error occurred

Notes

Team admins (owner or admin role) can configure team permissions
Team admins can set user-specific overrides
Users cannot modify their own permissions
Model IDs use format modelId:provider for uniqueness (same model can exist on multiple providers)
All limit values use credits (not USD)
Use -1 for unlimited