API and Integration View¶

This document defines the API design and integration specifications for the Personal Agents Platform domain. It is written for architects and engineers designing APIs and integrating with ConnectSoft Core Platform services.

The Personal Agents Platform exposes REST/gRPC APIs for all operations and integrates deeply with ConnectSoft Core Platform services for authentication, audit, configuration, storage, communications, billing, and agent execution.

Important

API Design Principles: 1. RESTful APIs for external access, gRPC for internal service-to-service communication 1. All APIs require authentication via Identity Platform 1. Personal-tenant isolation enforced at API level 1. All operations emit audit events 1. API versioning for backward compatibility

API Overview¶

API Architecture¶

graph TB
    subgraph Clients["Clients"]
        WebUI[Web UI]
        Mobile[Mobile App]
        API_Client[API Clients]
    end

    subgraph Gateway["API Gateway"]
        GatewayAPI[API Gateway<br/>Authentication<br/>Rate Limiting]
    end

    subgraph Services["Microservices"]
        PIP[Personal Identity<br/>& Profile Service]
        AC[Agent Catalog<br/>Service]
        PW[Pack & Workflow<br/>Service]
        AO[Agent Orchestration<br/>Service]
        SA[Suggestion & Approval<br/>Service]
        C[Connector<br/>Service]
        DA[Dashboard & Analytics<br/>Service]
    end

    subgraph Platforms["ConnectSoft Platforms"]
        IDP[Identity Platform]
        Audit[Audit Platform]
        Config[Config Platform]
        Docs[Documents Platform]
        Comm[Communications Platform]
        Billing[Billing Platform]
        AI[AI Gateway]
    end

    Clients --> GatewayAPI
    GatewayAPI --> PIP
    GatewayAPI --> AC
    GatewayAPI --> PW
    GatewayAPI --> AO
    GatewayAPI --> SA
    GatewayAPI --> C
    GatewayAPI --> DA

    Services --> IDP
    Services --> Audit
    Services --> Config
    Services --> Docs
    Services --> Comm
    Services --> Billing
    AO --> AI

    style GatewayAPI fill:#e1f5ff
    style Services fill:#fff4e1
    style Platforms fill:#e8f5e9

Hold "Alt" / "Option" to enable pan & zoom

Service APIs¶

Personal Identity & Profile Service¶

Base URL: https://api.connectsoft.me/v1/identity

Key Endpoints:

POST /users - Create user account
GET /users/{userId} - Get user profile
PUT /users/{userId}/profile - Update user profile
GET /users/{userId}/subscription - Get subscription details
PUT /users/{userId}/subscription - Update subscription
DELETE /users/{userId} - Delete user account and all data

Integration:

Identity Platform: OAuth2/OIDC authentication, user management
Billing Platform: Subscription management, usage tracking
Config Platform: User preferences storage

Agent Catalog Service¶

Base URL: https://api.connectsoft.me/v1/agents

Key Endpoints:

GET /templates - List available agent templates
GET /templates/{templateId} - Get agent template details
POST /instances - Create agent instance
GET /instances - List user's agent instances
GET /instances/{instanceId} - Get agent instance
PUT /instances/{instanceId} - Update agent instance configuration
DELETE /instances/{instanceId} - Delete agent instance

Integration:

Config Platform: Agent behavior configurations
Identity Platform: User authentication

Pack & Workflow Service¶

Base URL: https://api.connectsoft.me/v1/packs

Key Endpoints:

GET /packs - List user's packs
POST /packs - Create pack (from template or custom)
GET /packs/{packId} - Get pack details
PUT /packs/{packId} - Update pack
DELETE /packs/{packId} - Delete pack
POST /packs/{packId}/install - Install prebuilt pack
GET /workflows - List workflows
POST /workflows - Create workflow
GET /workflows/{workflowId} - Get workflow details
PUT /workflows/{workflowId} - Update workflow
POST /workflows/{workflowId}/triggers - Create workflow trigger
PUT /workflows/{workflowId}/triggers/{triggerId} - Update trigger

Integration:

Agent Catalog Service: Agent instance references
Config Platform: Workflow definitions and settings
Identity Platform: User authentication

Agent Orchestration Service¶

Base URL: https://api.connectsoft.me/v1/orchestration

Key Endpoints:

POST /runs - Execute agent run (manual trigger)
GET /runs - List agent runs
GET /runs/{runId} - Get run details
GET /runs/{runId}/steps - Get run steps
POST /runs/{runId}/cancel - Cancel running execution
GET /workflows/{workflowId}/executions - List workflow executions
GET /workflows/{workflowId}/executions/{executionId} - Get execution details

Integration:

AI Gateway & Agent Runtime: Agent execution
Agent Catalog Service: Agent instance definitions
Pack & Workflow Service: Workflow definitions
Connector Service: Data access
Audit Platform: Run logging

Suggestion & Approval Service¶

Base URL: https://api.connectsoft.me/v1/suggestions

Key Endpoints:

GET /suggestions - List suggestions (with filters)
GET /suggestions/{suggestionId} - Get suggestion details
POST /suggestions/{suggestionId}/approve - Approve suggestion
POST /suggestions/{suggestionId}/reject - Reject suggestion
POST /suggestions/{suggestionId}/edit - Edit and approve suggestion
POST /suggestions/bulk-approve - Bulk approve suggestions
GET /inbox - Get user suggestion inbox

Integration:

Agent Orchestration Service: Receives suggestion events
Connector Service: Executes approved actions
Communications Platform: Sends notifications
Audit Platform: Logs approval decisions

Connector Service¶

Base URL: https://api.connectsoft.me/v1/connectors

Key Endpoints:

GET /connectors - List available connector types
GET /connectors/configs - List user's connector configurations
POST /connectors/{type}/authorize - Initiate OAuth authorization
GET /connectors/{type}/callback - OAuth callback handler
GET /connectors/configs/{configId} - Get connector configuration
DELETE /connectors/configs/{configId} - Revoke connector
GET /connectors/configs/{configId}/snapshots - Get data snapshots
POST /connectors/configs/{configId}/sync - Trigger data sync

Integration:

External Services: Email (Gmail, Outlook), Calendar (Google Calendar, Outlook), File storage (Google Drive, OneDrive, Notion)
Documents Platform: File storage for uploaded files
Identity Platform: OAuth token management

Dashboard & Analytics Service¶

Base URL: https://api.connectsoft.me/v1/dashboard

Key Endpoints:

GET /dashboard - Get user dashboard
GET /analytics/usage - Get usage analytics
GET /analytics/runs - Get run history
GET /analytics/costs - Get cost tracking
GET /analytics/suggestions - Get suggestion analytics

Integration:

All Services: Aggregates data from all contexts
Audit Platform: Queries audit data for analytics
Agent Orchestration Service: Run history
Suggestion & Approval Service: Suggestion metrics

ConnectSoft Core Platform Integration¶

Identity Platform Integration¶

Purpose: Authentication, authorization, and user management.

Integration Points:

Authentication: OAuth2/OIDC flows
- Authorization Code flow for web apps
- Client Credentials flow for service-to-service
- Token validation and introspection
User Management:
- User registration and profile management
- Personal-tenant creation and management
- External IdP federation (Google, Microsoft)
Authorization:
- Personal-tenant isolation
- User-scoped resource access
- API token management

API Usage:

// Example: Authenticate user request
var token = await identityPlatform.ValidateTokenAsync(requestToken);
var user = await identityPlatform.GetUserAsync(token.UserId);
var tenant = await identityPlatform.GetTenantAsync(user.PersonalTenantId);

See: Identity Platform for platform details.

Audit Platform Integration¶

Purpose: Audit logging for compliance and transparency.

Integration Points:

Agent Run Events:
- AgentRunCreated, AgentRunStarted, AgentRunCompleted, AgentRunFailed
- Token usage and cost tracking
- Execution results and outputs
User Action Events:
- SuggestionCreated, SuggestionApproved, SuggestionRejected
- PackInstalled, PackDeleted
- ConnectorAuthorized, ConnectorRevoked
Personal Data Access:
- DataSnapshotCreated, DataSnapshotAccessed
- ConnectorExecution events

API Usage:

// Example: Log agent run
await auditPlatform.LogEventAsync(new AuditEvent
{
    EventType = "AgentRunCompleted",
    UserId = run.UserId,
    TenantId = run.PersonalTenantId,
    ResourceId = run.AgentRunId,
    Details = new { TokensUsed = run.TokensUsed, Cost = run.Cost }
});

See: Audit Platform for platform details.

Config Platform Integration¶

Purpose: User preferences, agent configurations, and feature flags.

Integration Points:

User Preferences:
- Timezone, language, notification preferences
- Privacy settings
Agent Configurations:
- Agent behavior rules
- Tool configurations
- Prompt templates
Workflow Definitions:
- Workflow step definitions
- Trigger configurations
Feature Flags:
- Per-user feature flags
- Gradual rollout flags

API Usage:

// Example: Get user preferences
var preferences = await configPlatform.GetConfigAsync(
    tenantId: user.PersonalTenantId,
    key: "user.preferences"
);

// Example: Store agent configuration
await configPlatform.SetConfigAsync(
    tenantId: user.PersonalTenantId,
    key: $"agent.{instanceId}.config",
    value: agentConfig
);

See: Config Platform for platform details.

Documents Platform Integration¶

Purpose: File storage for user uploads and agent-generated content.

Integration Points:

File Upload:
- User-uploaded files (PDFs, DOCX, TXT)
- File metadata and versioning
Agent-Generated Content:
- Agent summaries and reports
- Workflow outputs

API Usage:

// Example: Upload file
var document = await documentsPlatform.UploadFileAsync(
    tenantId: user.PersonalTenantId,
    fileName: "expenses.csv",
    contentType: "text/csv",
    stream: fileStream
);

// Example: Get file
var file = await documentsPlatform.GetFileAsync(
    tenantId: user.PersonalTenantId,
    documentId: documentId
);

See: Documents Platform for platform details.

Communications Platform Integration¶

Purpose: Email, SMS, and in-app notifications.

Integration Points:

Email Platform:
- Email notifications for agent suggestions
- Workflow summary emails
- Scheduled run result emails
SMS Gateway Service:
- SMS notifications for critical alerts (optional)
Notifications Platform:
- In-app notifications for suggestions
- Real-time notification delivery

API Usage:

// Example: Send email notification
await communicationsPlatform.SendEmailAsync(new EmailMessage
{
    To = user.Email,
    Subject = "New Agent Suggestions",
    Body = $"You have {count} new suggestions from your agents.",
    TemplateId = "suggestion-notification"
});

// Example: Send in-app notification
await communicationsPlatform.SendNotificationAsync(new Notification
{
    UserId = user.UserId,
    Title = "Agent Run Complete",
    Message = "Your morning routine workflow has completed.",
    Type = NotificationType.Info
});

See: Communications Platform for platform details.

See: Email Platform for email service details.

See: SMS Gateway Service for SMS service details.

See: Notifications Platform for notifications service details.

Billing & Subscription Platform Integration¶

Purpose: Subscription management, usage tracking, and invoicing.

Integration Points:

Subscription Management:
- Create, update, cancel subscriptions
- Tier management (Free, Pro, Family, Creator)
- Billing cycle management (monthly, annual)
Usage Tracking:
- Agent runs per month
- Token usage tracking
- Storage usage tracking
Billing & Invoicing:
- Invoice generation
- Payment processing
- Usage-based billing

API Usage:

// Example: Track agent run usage
await billingPlatform.RecordUsageAsync(new UsageRecord
{
    TenantId = user.PersonalTenantId,
    Metric = "agent.runs",
    Quantity = 1,
    Timestamp = DateTime.UtcNow
});

// Example: Check usage limits
var usage = await billingPlatform.GetUsageAsync(
    tenantId: user.PersonalTenantId,
    metric: "agent.runs",
    period: TimePeriod.ThisMonth
);
var limit = await billingPlatform.GetLimitAsync(
    tenantId: user.PersonalTenantId,
    metric: "agent.runs"
);
if (usage.Quantity >= limit.Quantity)
{
    throw new UsageLimitExceededException();
}

See: Billing & Subscription Platform for platform details.

AI Gateway & Agent Runtime Integration¶

Purpose: Agent execution, model routing, and token tracking.

Integration Points:

Agent Execution:
- Execute agent with configuration
- Model routing and selection
- Tool invocation
Token Tracking:
- Track tokens used per run
- Cost calculation
- Usage reporting
Agent Runtime:
- Agent Template execution
- Conversation/turn persistence
- Tool registration and execution

API Usage:

// Example: Execute agent
var execution = await aiGateway.ExecuteAgentAsync(new AgentExecutionRequest
{
    AgentInstanceId = instanceId,
    Configuration = agentConfig,
    Inputs = inputs,
    Tools = availableTools
});

var result = await execution.WaitForCompletionAsync();
var tokensUsed = result.TokensUsed;
var cost = result.Cost;

See: AI Factory Overview for Factory capabilities.

See: Agent System Overview for agent system architecture.

External Connector Integrations¶

Email Connector (Gmail, Outlook)¶

Authorization: OAuth2

Operations:

Read inbox (list emails, get email content)
Create drafts (not auto-send)
Search emails

API Endpoints:

Gmail API: https://gmail.googleapis.com/gmail/v1
Microsoft Graph API: https://graph.microsoft.com/v1.0

Calendar Connector (Google Calendar, Outlook Calendar)¶

Authorization: OAuth2

Operations:

Read events (list events, get event details)
Create events (as suggestions, not auto-create)
Update events (after approval)

API Endpoints:

Google Calendar API: https://www.googleapis.com/calendar/v3
Microsoft Graph API: https://graph.microsoft.com/v1.0

File Upload Connector¶

Operations:

Upload files (PDF, DOCX, TXT)
Store in Documents Platform
Process files for agent use

Storage: Documents Platform

Notion Connector (Future)¶

Authorization: OAuth2

Operations:

Read pages and databases
Create pages (as suggestions)
Update pages (after approval)

Google Drive Connector (Future)¶

Authorization: OAuth2

Operations:

List files
Read file content
Create files (as suggestions)

OneDrive Connector (Future)¶

Authorization: OAuth2

Operations:

List files
Read file content
Create files (as suggestions)

API Authentication and Security¶

Authentication Flow¶

User authenticates via Identity Platform (OAuth2/OIDC)
Client receives access token
Client includes token in API requests (Authorization header)
API Gateway validates token with Identity Platform
Request forwarded to microservice with user context

Personal-Tenant Isolation¶

All API requests include user context
Resources scoped to user's personal tenant
Cross-tenant access prevented at API level
Audit Platform logs all access

Rate Limiting¶

Per-user rate limits based on subscription tier
API Gateway enforces rate limits
Usage tracked via Billing Platform

Domain Overview - Domain overview
Domain Vision and Scope - Vision and scope
Bounded Contexts and Context Map - Domain boundaries
Domain Model and Aggregates - Domain model
Processes and Flows - Business processes
High-Level Design - System architecture
Reporting and Analytics - KPIs and analytics
Identity Platform - Identity service
Audit Platform - Audit service
Config Platform - Config service

API and Integration View¶

API Overview¶

API Architecture¶

Service APIs¶

Personal Identity & Profile Service¶

Agent Catalog Service¶

Pack & Workflow Service¶

Agent Orchestration Service¶

Suggestion & Approval Service¶

Connector Service¶

Dashboard & Analytics Service¶

ConnectSoft Core Platform Integration¶

Identity Platform Integration¶

Audit Platform Integration¶

Config Platform Integration¶

Documents Platform Integration¶

Communications Platform Integration¶

Billing & Subscription Platform Integration¶

AI Gateway & Agent Runtime Integration¶

External Connector Integrations¶

Email Connector (Gmail, Outlook)¶

Calendar Connector (Google Calendar, Outlook Calendar)¶

File Upload Connector¶

Notion Connector (Future)¶

Google Drive Connector (Future)¶

OneDrive Connector (Future)¶

API Authentication and Security¶

Authentication Flow¶

Personal-Tenant Isolation¶

Rate Limiting¶

Related Documents¶