Apps — Hypery Docs

Overview

The Apps API lets you build interfaces for managing OAuth apps, credentials, and settings.

Authentication: OAuth token
Required Scopes: apps:read, apps:write

List Apps

Get user's OAuth apps.

Endpoint: GET /api/apps

const response = await fetch('https://hypery.ai/api/apps', {
  headers: {
    'Authorization': `Bearer ${oauthToken}`
  }
})
 
const { data } = await response.json()
console.log(data.apps)

response = requests.get(
    'https://hypery.ai/api/apps',
    headers={'Authorization': f'Bearer {oauth_token}'}
)
 
apps = response.json()['data']['apps']

curl https://hypery.ai/api/apps \
  -H "Authorization: Bearer OAUTH_TOKEN"

Response:

{
  "success": true,
  "data": {
    "apps": [
      {
        "id": "507f...",
        "name": "My App",
        "description": "App description",
        "oauth": {
          "clientId": "app_1699564800_abc123",
          "redirectUris": ["https://app.com/callback"],
          "scopes": ["ai:chat", "user:read"]
        },
        "status": "active",
        "totalInstalls": 42,
        "createdAt": "2025-11-01T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalCount": 5,
      "totalPages": 1
    }
  }
}

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 20, max: 100)
`teamId`	string	Filter by team

Create App

Create a new OAuth application.

Endpoint: POST /api/apps

const response = await fetch('https://hypery.ai/api/apps', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${oauthToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My App',
    description: 'App description',
    category: 'developer-tools',
    redirectUris: ['https://myapp.com/callback'],
    scopes: ['ai:chat', 'user:read']
  })
})
 
const { data } = await response.json()
console.log('Client ID:', data.app.oauth.clientId)

response = requests.post(
    'https://hypery.ai/api/apps',
    headers={'Authorization': f'Bearer {oauth_token}'},
    json={
        'name': 'My App',
        'description': 'App description',
        'category': 'developer-tools',
        'redirectUris': ['https://myapp.com/callback'],
        'scopes': ['ai:chat', 'user:read']
    }
)
 
app = response.json()['data']['app']
print('Client ID:', app['oauth']['clientId'])

curl -X POST https://hypery.ai/api/apps \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "description": "App description",
    "category": "developer-tools",
    "redirectUris": ["https://myapp.com/callback"],
    "scopes": ["ai:chat", "user:read"]
  }'

Input Parameters

Parameter	Type	Required	Description
`name`	string	Yes	App name (max 100 chars)
`description`	string	No	App description (max 500 chars)
`category`	string	Yes	App category (see below)
`redirectUris`	array	Yes	OAuth redirect URLs (at least one)
`scopes`	array	Yes	Requested scopes (at least one)
`image`	string	No	App icon URL
`website`	string	No	App website URL
`teamSlug`	string	No	Create for specific team

Categories:

productivity
entertainment
education
business
developer-tools
other

Available scopes:

read, write
ai:chat, ai:completions, ai:models, ai:images, ai:embeddings, ai:audio
billing:read, billing:charge

Full reference: OAuth scopes.

Get App

Get details of a specific app.

Endpoint: GET /api/apps/:id

const response = await fetch(
  `https://hypery.ai/api/apps/${appId}`,
  { headers: { 'Authorization': `Bearer ${oauthToken}` } }
)
 
const { app } = await response.json()

response = requests.get(
    f'https://hypery.ai/api/apps/{app_id}',
    headers={'Authorization': f'Bearer {oauth_token}'}
)
 
app = response.json()['app']

curl https://hypery.ai/api/apps/APP_ID \
  -H "Authorization: Bearer OAUTH_TOKEN"

Regenerate Credentials

Generate new client secret (invalidates old one).

Endpoint: POST /api/apps/:id/regenerate-credentials

const response = await fetch(
  `https://hypery.ai/api/apps/${appId}/regenerate-credentials`,
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${oauthToken}` }
  }
)
 
const { clientSecret } = await response.json()
console.log('New secret:', clientSecret)

response = requests.post(
    f'https://hypery.ai/api/apps/{app_id}/regenerate-credentials',
    headers={'Authorization': f'Bearer {oauth_token}'}
)
 
secret = response.json()['clientSecret']
print('New secret:', secret)

curl -X POST https://hypery.ai/api/apps/APP_ID/regenerate-credentials \
  -H "Authorization: Bearer OAUTH_TOKEN"

This immediately invalidates the old client secret. All existing OAuth flows using the old secret will fail.

Update App

Modify app settings and configuration.

Endpoint: PUT /api/apps/:id

const response = await fetch(`https://hypery.ai/api/apps/${appId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${oauthToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Updated App Name',
    description: 'Updated description',
    oauth: {
      redirectUris: ['https://newapp.com/callback'],
      scopes: ['ai:chat', 'teams:read']
    }
  })
})
 
const { data } = await response.json()

response = requests.put(
    f'https://hypery.ai/api/apps/{app_id}',
    headers={'Authorization': f'Bearer {oauth_token}'},
    json={
        'name': 'Updated App Name',
        'description': 'Updated description',
        'oauth': {
            'redirectUris': ['https://newapp.com/callback'],
            'scopes': ['ai:chat', 'teams:read']
        }
    }
)

curl -X PUT https://hypery.ai/api/apps/APP_ID \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated App Name",
    "description": "Updated description",
    "oauth": {
      "redirectUris": ["https://newapp.com/callback"],
      "scopes": ["ai:chat", "teams:read"]
    }
  }'

Input Parameters

Parameter	Type	Required	Description
`name`	string	No	App name
`description`	string	No	App description
`image`	string	No	App icon URL
`website`	string	No	App website URL
`category`	string	No	App category
`oauth.redirectUris`	array	No	OAuth redirect URLs
`oauth.scopes`	array	No	Requested scopes
`settings.webhookUrl`	string	No	Webhook URL
`settings.allowedOrigins`	array	No	CORS allowed origins

Upload App Icon

Update app icon/logo.

Endpoint: POST /api/apps/:id/icon

const formData = new FormData()
formData.append('image', fileInput.files[0])
 
const response = await fetch(
  `https://hypery.ai/api/apps/${appId}/icon`,
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${oauthToken}` },
    body: formData
  }
)
 
const { imageUrl } = await response.json()

files = {'image': open('app-icon.png', 'rb')}
 
response = requests.post(
    f'https://hypery.ai/api/apps/{app_id}/icon',
    headers={'Authorization': f'Bearer {oauth_token}'},
    files=files
)

curl -X POST https://hypery.ai/api/apps/APP_ID/icon \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -F "image=@app-icon.png"

Required Role: Team owner or admin

Delete App

Delete an OAuth app permanently.

Endpoint: DELETE /api/apps/:id

await fetch(`https://hypery.ai/api/apps/${appId}`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${oauthToken}` }
})

requests.delete(
    f'https://hypery.ai/api/apps/{app_id}',
    headers={'Authorization': f'Bearer {oauth_token}'}
)

curl -X DELETE https://hypery.ai/api/apps/APP_ID \
  -H "Authorization: Bearer OAUTH_TOKEN"

Error Responses

Invalid Category

{
  "success": false,
  "error": "Invalid app data",
  "details": [
    {
      "path": ["category"],
      "message": "Invalid enum value..."
    }
  ]
}

Status Code: 400

Missing Required Field

{
  "success": false,
  "error": "Invalid app data"
}

Status Code: 400

Next Steps

Teams API

Create teams for your apps

OAuth

Learn about OAuth flow