Apps — Hypery Docs

Overview

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

Authentication: OAuth token
Scopes: any valid token can list and read apps; creating, updating or deleting an app, and uploading its icon, need write. Regenerating credentials, transferring an app and changing its status are Hypery browser-session only. See OAuth scopes.

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", "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', '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', '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", "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
`brandColor`	string	No	Hex brand color for hosted sign-in/consent pages (e.g. `#6C47FF`)
`website`	string	No	App website URL
`termsOfService`	string	No	Terms of service URL
`privacyPolicy`	string	No	Privacy policy 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
config:store

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 { data } = await response.json()
console.log(data.app)

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

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

Example response:

{
  "success": true,
  "data": {
    "app": {
      "id": "507f...",
      "name": "My App",
      "description": "App description",
      "image": "https://cdn.example.com/icon.png",
      "brandColor": "#6C47FF",
      "website": "https://myapp.com",
      "termsOfService": "https://myapp.com/terms",
      "privacyPolicy": "https://myapp.com/privacy",
      "category": "developer-tools",
      "tags": ["ai"],
      "status": "draft",
      "isPublic": false,
      "oauth": {
        "clientId": "app_1699564800_abc123",
        "redirectUris": ["https://myapp.com/callback"],
        "scopes": ["ai:chat", "read"]
      },
      "settings": {
        "webhookUrl": "https://myapp.com/webhooks",
        "allowedOrigins": ["https://myapp.com"],
        "rateLimits": {
          "requestsPerMinute": 60,
          "requestsPerHour": 1000,
          "requestsPerDay": 10000
        }
      }
    }
  }
}

Output Parameters

Field	Type	Description
`brandColor`	string	Hex color used on hosted OAuth login/consent screens
`website`	string	Public website URL (stored as `url` in the database)
`termsOfService`	string	Terms of service URL
`privacyPolicy`	string	Privacy policy URL
`settings.rateLimits`	object	Per-minute / hour / day request caps

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',
    brandColor: '#6C47FF',
    website: 'https://myapp.com',
    oauth: {
      redirectUris: ['https://newapp.com/callback'],
      scopes: ['ai:chat', 'read']
    },
    settings: {
      rateLimits: {
        requestsPerMinute: 60,
        requestsPerHour: 1000,
        requestsPerDay: 10000
      }
    }
  })
})
 
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',
        'brandColor': '#6C47FF',
        'website': 'https://myapp.com',
        'oauth': {
            'redirectUris': ['https://newapp.com/callback'],
            'scopes': ['ai:chat', 'read']
        },
        'settings': {
            'rateLimits': {
                'requestsPerMinute': 60,
                'requestsPerHour': 1000,
                'requestsPerDay': 10000
            }
        }
    }
)

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",
    "brandColor": "#6C47FF",
    "website": "https://myapp.com",
    "oauth": {
      "redirectUris": ["https://newapp.com/callback"],
      "scopes": ["ai:chat", "read"]
    },
    "settings": {
      "rateLimits": {
        "requestsPerMinute": 60,
        "requestsPerHour": 1000,
        "requestsPerDay": 10000
      }
    }
  }'

Input Parameters

Parameter	Type	Required	Description
`name`	string	No	App name
`description`	string	No	App description
`image`	string	No	App icon URL
`brandColor`	string	No	Hex brand color (e.g. `#6C47FF`); empty string clears it
`website`	string	No	App website URL
`termsOfService`	string	No	Terms of service URL
`privacyPolicy`	string	No	Privacy policy URL
`category`	string	No	App category
`oauth.redirectUris`	array	No	OAuth redirect URLs
`oauth.scopes`	array	No	Requested scopes
`oauth.deviceFlow`	boolean	No	Enable or disable the device flow. Not accepted from an OAuth access token (`403`); use a Hypery session or API key.
`settings.webhookUrl`	string	No	Webhook URL
`settings.allowedOrigins`	array	No	CORS allowed origins
`settings.rateLimits`	object	No	`requestsPerMinute` / `requestsPerHour` / `requestsPerDay`

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