REST API documentation for the Supyagent Cloud service, including authentication, request format, and error handling.

API Reference

The Supyagent Cloud API is a REST API at https://app.supyagent.com/api/v1/. All requests require authentication with your API key.

Authentication

Every request must include your API key in the Authorization header:

Authorization: Bearer sk_live_abc123...

API keys are created on the Supyagent dashboard under Settings > API Keys.

API Key Format

Keys follow the format sk_live_<random>. Keys are:

HMAC-hashed before storage (the raw key is never saved)
Scoped to your user account and all connected integrations
Revocable at any time from the dashboard

Authentication Errors

Status	Body	Cause
`401`	`{"error": "Missing authorization header"}`	No `Authorization` header
`401`	`{"error": "Invalid API key"}`	Key is incorrect, expired, or revoked
`403`	`{"error": "Permission denied"}`	Key is valid but lacks permission for this action

Base URL

https://app.supyagent.com/api/v1/

Request Format

Content-Type: application/json for POST/PUT/PATCH requests
Query parameters for GET request filtering
Path parameters for resource identification

Example Request

curl -X GET "https://app.supyagent.com/api/v1/google/gmail/messages?limit=5" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json"

Response Format

All responses follow a consistent JSON structure:

Success

{
  "data": {
    "messages": [...],
    "next_cursor": "abc123"
  }
}

Error

{
  "error": "Description of what went wrong",
  "code": "PROVIDER_ERROR",
  "details": {}
}

API Endpoints

Google

Method	Endpoint	Description
`GET`	`/google/gmail/messages`	List emails
`GET`	`/google/gmail/messages/{id}`	Get email details
`POST`	`/google/gmail/send`	Send an email
`GET`	`/google/calendar/events`	List calendar events
`POST`	`/google/calendar/events`	Create a calendar event
`PUT`	`/google/calendar/events/{id}`	Update an event
`DELETE`	`/google/calendar/events/{id}`	Delete an event
`GET`	`/google/drive/files`	List/search files
`GET`	`/google/drive/files/{id}/content`	Download file content

Slack

Method	Endpoint	Description
`GET`	`/slack/channels`	List channels
`GET`	`/slack/messages`	List messages in a channel
`POST`	`/slack/messages`	Send a message
`GET`	`/slack/users`	List workspace users

GitHub

Method	Endpoint	Description
`GET`	`/github/repos`	List repositories
`GET`	`/github/repos/{owner}/{repo}`	Get repository details
`GET`	`/github/repos/{owner}/{repo}/issues`	List issues
`POST`	`/github/repos/{owner}/{repo}/issues`	Create an issue
`GET`	`/github/repos/{owner}/{repo}/pulls`	List pull requests
`POST`	`/github/repos/{owner}/{repo}/pulls`	Create a pull request

Discord

Method	Endpoint	Description
`GET`	`/discord/guilds`	List servers
`GET`	`/discord/guilds/{id}/channels`	List channels
`GET`	`/discord/channels/{id}/messages`	Read messages
`POST`	`/discord/channels/{id}/messages`	Send a message

Microsoft 365

Method	Endpoint	Description
`GET`	`/microsoft/mail/messages`	List emails
`POST`	`/microsoft/mail/send`	Send an email
`GET`	`/microsoft/calendar/events`	List calendar events
`POST`	`/microsoft/calendar/events`	Create an event
`GET`	`/microsoft/drive/files`	List/search files

Notion

Method	Endpoint	Description
`GET`	`/notion/pages/{id}`	Get page content
`POST`	`/notion/pages`	Create a page
`POST`	`/notion/databases/{id}/query`	Query a database
`POST`	`/notion/search`	Search workspace

Inbox

Method	Endpoint	Description
`GET`	`/inbox/events`	List inbox events
`PATCH`	`/inbox/events/{id}`	Mark event as read/archived

Endpoints for listing, searching, and filtering available tools. Every tool in the response includes metadata.connected (true/false) indicating whether the user has the required integration active.

Method	Endpoint	Description
`GET`	`/tools`	List connected tools (or all tools with `?all=true`)
`GET`	`/tools/search/{query}`	Fuzzy search across tool names and descriptions
`GET`	`/tools/names/{query}`	Search by tool name only
`GET`	`/tools/provider/{provider}`	Filter by provider (e.g. `google`, `slack`)
`GET`	`/tools/service/{service}`	Filter by service (e.g. `gmail`, `calendar`)

`GET /tools`

Returns tools for the authenticated user's connected integrations.

Parameter	Type	Description
`all`	query, optional	Set to `true` to return all available tools, not just connected ones

# Connected tools only
curl -H "Authorization: Bearer $KEY" https://app.supyagent.com/api/v1/tools

# All tools with connected status
curl -H "Authorization: Bearer $KEY" https://app.supyagent.com/api/v1/tools?all=true

`GET /tools/search/{query}`

Fuzzy search across tool names and descriptions. Results are ranked by relevance score (0–1). Matches partial keywords across providers.

# "send email" matches gmail, resend, supymail, slack, etc.
curl -H "Authorization: Bearer $KEY" \
  https://app.supyagent.com/api/v1/tools/search/send%20email

`GET /tools/names/{query}`

Search by tool name only (not description). Useful when you know the exact tool name or prefix.

curl -H "Authorization: Bearer $KEY" \
  https://app.supyagent.com/api/v1/tools/names/gmail

`GET /tools/provider/{provider}`

Returns all tools for a specific provider.

curl -H "Authorization: Bearer $KEY" \
  https://app.supyagent.com/api/v1/tools/provider/google

`GET /tools/service/{service}`

Returns all tools for a specific service.

curl -H "Authorization: Bearer $KEY" \
  https://app.supyagent.com/api/v1/tools/service/gmail

Tool Response Shape

{
  "ok": true,
  "data": {
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "gmail_send_message",
          "description": "Send an email via Gmail...",
          "parameters": { "..." }
        },
        "metadata": {
          "provider": "google",
          "service": "gmail",
          "permission": "gmail.send",
          "method": "POST",
          "path": "/api/v1/gmail/send",
          "connected": true
        },
        "score": 0.42
      }
    ],
    "total": 23
  }
}

score is only present on /tools/search and /tools/names responses. connected is present on all tool endpoints.

Common Query Parameters

Parameter	Type	Description
`limit`	`int`	Maximum number of results (default varies by endpoint)
`cursor`	`str`	Pagination cursor from previous response
`q` or `search`	`str`	Search query (endpoint-specific)

Rate Limits

Tier	Requests/minute	Requests/day
Free	60	1,000
Pro	300	10,000
Team	1,000	100,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1678901234

When rate limited, the API returns:

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "retry_after": 30
}

Error Codes

Code	HTTP Status	Description
`AUTH_REQUIRED`	401	Missing or invalid API key
`PERMISSION_DENIED`	403	API key lacks permission for this action
`NOT_FOUND`	404	Resource not found
`PROVIDER_ERROR`	502	Upstream provider returned an error
`PROVIDER_UNAVAILABLE`	503	Upstream provider is unreachable
`RATE_LIMITED`	429	Too many requests
`INTEGRATION_EXPIRED`	401	OAuth token expired and refresh failed
`INTEGRATION_REVOKED`	401	User revoked access to the integration
`VALIDATION_ERROR`	400	Invalid request parameters

Usage Logging

Every API call is logged with:

Timestamp
Endpoint called
Provider and action
Response status
Tokens/units consumed

View your usage on the dashboard under Settings > Usage.

What's Next

Connecting -- Set up integrations and API keys
Providers -- Detailed per-provider guides
Inbox -- Event-driven AI inbox

API Reference

API Reference

Authentication

API Key Format

Authentication Errors

Base URL

Request Format

Example Request

Response Format

Success

Error

API Endpoints

Google

Slack

GitHub

Discord

Microsoft 365

Notion

Inbox

Tool Discovery

`GET /tools`

`GET /tools/search/{query}`

`GET /tools/names/{query}`

`GET /tools/provider/{provider}`

`GET /tools/service/{service}`

Tool Response Shape

Common Query Parameters

Rate Limits

Error Codes

Usage Logging

What's Next

On this page