API overview
Use Personal Access Tokens to connect external clients to Pegasus.
Pegasus API access lets external clients authenticate with a Personal Access Token (PAT) and perform actions within selected scopes.
API access is available on Pro and Ultra plans. Free workspaces see an upgrade prompt instead of the token creator.
What you can use it for
- Build an internal tool that chats with a Pegasus bot.
- Read usage analytics from another system.
- Manage bots or documents if the token has write scopes.
- Bind automation to Personal or Team workspace context.
What the docs page is not
This user guide explains the in-app token workflow. Full public API docs and playground are planned for API Product v1.
We're actively working on this. Check back soon, or contact your workspace owner for the latest status.
A public developer docs/playground surface is on the roadmap. Until then, use this guide for token safety and workspace binding.
Core safety rule
Treat tokens like passwords. Anyone with a token can call the API as you within its scopes.
Create a token
Tokens are created from Settings → API Tokens.
API access requires Pro or Ultra. If you see "Upgrade to use the API", switch to an eligible workspace or upgrade.
Open Settings
Go to Settings and choose the API Tokens tab.Click Create token
The dialog asks for a name, scopes, and expiry.Name the token
Use a purpose-based name such as "Production API client".Pick scopes
Start narrow. Scopes cannot be changed later.Choose expiry
Pick 30, 60, 90, 180, or 365 days.Copy and save
Pegasus shows the token once. Store it before closing the dialog.
Presets
- Chat API only - good for sending messages.
- Read-only - good for reporting or monitoring.
- Bot management - broader access for trusted automation.
Scope reference
Scopes limit what a token can do. Pick the smallest set that lets your client work.
| Scope label | Use |
|---|---|
| Read your profile | Read basic user profile data. |
| Read your subscription | Inspect plan/quota information. |
| Read available models | List models the workspace can use. |
| Read bots & documents | List/read bots and document metadata. |
| Create, update, delete bots | Manage bots and documents. |
| Read API conversations | Read conversations created for API usage. |
| Create, delete API conversations | Create or remove API conversations. |
| Send chat messages | Send messages to bots. |
| Read usage analytics | Read usage reports. |
Preset mapping
- Chat API only: conversations and messages needed for chat.
- Read-only: profile/subscription/models/bots/usage read scopes.
- Bot management: bot read/write plus supporting read scopes.
Scopes cannot be edited after token creation. Revoke the token and create a new one.
Workspace binding
New tokens are bound to the active workspace at creation time.
Personal binding
Create the token while in Personal workspace. The token acts as you against personal bots, conversations, usage, and subscription context.
Team binding
Create the token while switched into a Team workspace. The token acts within that team context and respects team role, seat, read-only, and quota state.
Read-only teams
If the team is pending cancellation or quota is disabled, Pegasus can block new token creation and show: "Team API access is read-only".
Choosing the right binding
- Personal automation: create in Personal.
- Team chatbot automation: create in the team.
- Reporting across team usage: create in the team, with usage read scopes.
- Testing: create a short-expiry token in the same workspace where you will test.