Platform API

The Platform API provides programmatic CRUD over your SuitePortal configuration — organizations, syncs, views, agents, payments, and more.

Base URL: https://suiteportal.io/api/platform/v1

API Reference: suiteportal.io/api/platform/v1/docs

Authentication

API key (recommended for integrations)

Create a key in Configuration > API or via the API itself. Keys are prefixed with sp_.

curl -H "Authorization: Bearer sp_live_abc123..." \
  https://suiteportal.io/api/platform/v1/whoami

OAuth2 bearer token (for MCP / AI agents)

Agents authenticate via Better Auth's OAuth2 flow and receive a JWT. This is the same flow used by the MCP server — no additional setup required.

curl -H "Authorization: Bearer eyJhbG..." \
  https://suiteportal.io/api/platform/v1/whoami

Session cookie (web app)

If you're calling the Platform API from the SuitePortal web app, your session cookie is sent automatically. No Authorization header needed.

Common workflows

Check your context

GET /api/platform/v1/whoami

Returns your user, active organization, membership role, permissions, and resource metrics (MAU, storage, agent credits, active API keys).

List and trigger syncs

# List all sync configs
GET /api/platform/v1/sync-configs

# Trigger a sync
POST /api/platform/v1/sync-configs/{id}/trigger

# Check run status
GET /api/platform/v1/sync-configs/{id}/runs

Manage agents

# List agents
GET /api/platform/v1/agents

# Restart an agent
POST /api/platform/v1/agents/{id}/restart

# Get conversations
GET /api/platform/v1/agents/{id}/conversations

Payment operations

# Get Pay config
GET /api/platform/v1/pay/config

# List payments
GET /api/platform/v1/pay/payments?status=SUCCEEDED

# Create checkout
POST /api/platform/v1/pay/checkout

Pagination

List endpoints accept page and pageSize query parameters:

GET /api/platform/v1/sync-configs?page=2&pageSize=10

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 42,
    "page": 2,
    "pageSize": 10,
    "totalPages": 5
  }
}

Default page size is 25, maximum is 100.

Error handling

All errors return a consistent JSON body:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required permission: sync:create"
  }
}

Resource groups

The API is organized into 11 resource groups. See the API Reference for full endpoint details.

OpenAPI spec

The raw OpenAPI 3.0 JSON spec is available at:

GET /api/platform/v1/openapi

Use it to generate client SDKs, import into Postman, or integrate with any OpenAPI-compatible tooling.