Api Webhooks
This guide walks you through api webhooks in Maya OS. By the end you will understand the core building blocks, how they fit into the runtime, and how to put them to work for your team. Each section is self-contained, so feel free to jump to whatever you need.
Overview
Maya OS is built around three primitives: agents that act, modules that hold domain data, and channels that connect you to the outside world. Everything in this guide composes from those three. Once you grasp how they relate, the rest of the platform becomes predictable.
Throughout the docs we assume you have already created a workspace and have at least one module enabled. If you have not, start with the Quickstart and return here when your workspace is live.
Prerequisites
Before you begin, make sure you have an active workspace, an admin or developer role, and an API key scoped to the resources you intend to touch. You can generate a key from Settings → Developers → API keys.
What you'll need
- An active Maya OS workspace
- A scoped API key with the right permissions
- Your base region URL (US or EU)
A first request
The example below authenticates with your bearer token and lists the agents available in your workspace. Replace the placeholder token with the key you generated above.
curl https://api.maya-os.com/v1/agents \
-H "Authorization: Bearer sk_live_8f2a...c019" \
-H "Content-Type: application/json"A successful call returns a paginated list of agents, each with its current status and the module it belongs to.
Tip
Use a test-mode key (sk_test_…) while you build. Test keys operate on a sandboxed copy of your workspace, so you can experiment freely without touching production data.
Next steps
With the basics in place, you can wire api webhooks into your own automations, subscribe to webhooks for real-time updates, or hand control to an agent so the work happens without you. The pages in the sidebar go deeper on each path.