Your First API Call

In this page, you'll list available tools, run one, and understand the output.

List your available tools

See everything you can do:

supyagent service tools

Service Tools
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Tool                    ┃ Description                          ┃ Provider ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ gmail_list_messages     │ List messages from Gmail inbox        │ google   │
│ gmail_get_message       │ Get a specific email by ID           │ google   │
│ gmail_send_message      │ Send an email via Gmail              │ google   │
│ calendar_list_events    │ List upcoming calendar events        │ google   │
│ calendar_create_event   │ Create a new calendar event          │ google   │
│ slack_list_channels     │ List Slack channels                  │ slack    │
│ slack_send_message      │ Send a message to a Slack channel    │ slack    │
│ ...                     │ ...                                  │ ...      │
└─────────────────────────┴──────────────────────────────────────┴──────────┘

17 tools available
Run a tool: supyagent service run <tool_name> '<json_args>'

You can filter by provider:

supyagent service tools --provider google

Run your first tool

Let's list your recent emails:

supyagent service run gmail_list_messages '{}'

The '{}' is an empty JSON object — it means "use all defaults." You should see something like:

{
  "ok": true,
  "data": {
    "messages": [
      {
        "id": "18e3a4b2c1d0e5f6",
        "from": "alice@example.com",
        "subject": "Meeting tomorrow",
        "snippet": "Hey, just confirming our meeting at 2pm...",
        "date": "2026-02-25T10:30:00Z"
      },
      {
        "id": "18e3a4b2c1d0e5f7",
        "from": "notifications@github.com",
        "subject": "[supyagent] New issue: #42",
        "snippet": "A new issue was opened in supyagent/supyagent...",
        "date": "2026-02-25T09:15:00Z"
      }
    ]
  }
}

Understanding the output

Every tool returns the same structure:

Field	Meaning
`ok`	`true` if the call succeeded, `false` if it failed
`data`	The result (only present when `ok` is `true`)
`error`	Error message (only present when `ok` is `false`)

Try another tool

Check your calendar for today's events:

supyagent service run calendar_list_events '{"timeMin": "2026-02-25T00:00:00Z"}'

{
  "ok": true,
  "data": {
    "events": [
      {
        "id": "evt_abc123",
        "summary": "Team standup",
        "start": "2026-02-25T09:00:00-05:00",
        "end": "2026-02-25T09:15:00-05:00",
        "attendees": ["you@example.com", "team@example.com"]
      }
    ]
  }
}

Passing arguments

Tools accept JSON arguments. You can pass them in several ways:

# JSON string (most common)
supyagent service run gmail_list_messages '{"max_results": 5}'

# From a file
supyagent service run gmail_send_message -i message.json

# Flag-based
supyagent service run slack_send_message --channel "#general" --text "Hello!"

curl equivalent

Under the hood, the CLI is calling the Supyagent API. Here's the equivalent curl command:

curl -X POST https://app.supyagent.com/api/v1/google/gmail/messages \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

The CLI handles authentication, error formatting, and binary content automatically — so you don't need to use curl directly.

What if something goes wrong?

If a tool call fails, you'll see:

{
  "ok": false,
  "error": "Permission denied for gmail_send_message. Enable it on your dashboard."
}

Common errors:

Error	Fix
`Service API key expired`	Run `supyagent connect` again
`Permission denied`	Enable the permission on your dashboard
`Rate limit exceeded`	Wait a moment and try again
`Integration not connected`	Connect the integration on your dashboard

Next step

Generate Skills for Your IDE — Let your AI coding assistant use these tools automatically.

Your First API Call

On this page