Supyagent
Cloud Integrations

API Reference

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

StatusBodyCause
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

MethodEndpointDescription
GET/google/gmail/messagesList emails
GET/google/gmail/messages/{id}Get email details
POST/google/gmail/sendSend an email
GET/google/calendar/eventsList calendar events
POST/google/calendar/eventsCreate a calendar event
PUT/google/calendar/events/{id}Update an event
DELETE/google/calendar/events/{id}Delete an event
GET/google/drive/filesList/search files
GET/google/drive/files/{id}/contentDownload file content

Slack

MethodEndpointDescription
GET/slack/channelsList channels
GET/slack/messagesList messages in a channel
POST/slack/messagesSend a message
GET/slack/usersList workspace users

GitHub

MethodEndpointDescription
GET/github/reposList repositories
GET/github/repos/{owner}/{repo}Get repository details
GET/github/repos/{owner}/{repo}/issuesList issues
POST/github/repos/{owner}/{repo}/issuesCreate an issue
GET/github/repos/{owner}/{repo}/pullsList pull requests
POST/github/repos/{owner}/{repo}/pullsCreate a pull request

Discord

MethodEndpointDescription
GET/discord/guildsList servers
GET/discord/guilds/{id}/channelsList channels
GET/discord/channels/{id}/messagesRead messages
POST/discord/channels/{id}/messagesSend a message

Microsoft 365

MethodEndpointDescription
GET/microsoft/mail/messagesList emails
POST/microsoft/mail/sendSend an email
GET/microsoft/calendar/eventsList calendar events
POST/microsoft/calendar/eventsCreate an event
GET/microsoft/drive/filesList/search files

Notion

MethodEndpointDescription
GET/notion/pages/{id}Get page content
POST/notion/pagesCreate a page
POST/notion/databases/{id}/queryQuery a database
POST/notion/searchSearch workspace

Inbox

MethodEndpointDescription
GET/inbox/eventsList inbox events
PATCH/inbox/events/{id}Mark event as read/archived

Common Query Parameters

ParameterTypeDescription
limitintMaximum number of results (default varies by endpoint)
cursorstrPagination cursor from previous response
q or searchstrSearch query (endpoint-specific)

Rate Limits

TierRequests/minuteRequests/day
Free601,000
Pro30010,000
Team1,000100,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

CodeHTTP StatusDescription
AUTH_REQUIRED401Missing or invalid API key
PERMISSION_DENIED403API key lacks permission for this action
NOT_FOUND404Resource not found
PROVIDER_ERROR502Upstream provider returned an error
PROVIDER_UNAVAILABLE503Upstream provider is unreachable
RATE_LIMITED429Too many requests
INTEGRATION_EXPIRED401OAuth token expired and refresh failed
INTEGRATION_REVOKED401User revoked access to the integration
VALIDATION_ERROR400Invalid 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

Notion

Connect Notion to your agents for reading and managing pages, databases, and workspace content.

AI Inbox

Process webhook events from connected integrations with the AI Inbox -- event-driven agent automation.

On this page

API ReferenceAuthenticationAPI Key FormatAuthentication ErrorsBase URLRequest FormatExample RequestResponse FormatSuccessErrorAPI EndpointsGoogleSlackGitHubDiscordMicrosoft 365NotionInboxCommon Query ParametersRate LimitsError CodesUsage LoggingWhat's Next