Skip to main content

API Overview

The Ascend Platform REST API provides programmatic access to enterprise-grade agent governance, policy management, compliance automation, and real-time security orchestration. Built with banking-level security and multi-tenant isolation, our API powers mission-critical workflows for Fortune 500 companies.

Base URLs

Production:  https://pilot.owkai.app
Sandbox: https://sandbox-pilot.owkai.app

Enterprise Security Architecture

Authentication Methods

Ascend supports three authentication methods, each designed for specific use cases with industry-leading security standards:

MethodUse CaseSecurity StandardToken Lifetime
Cookie SessionsWeb applications, dashboardsHttpOnly, Secure, SameSite=Strict24 hours (configurable)
AWS Cognito JWTEnterprise SSO, mobile appsRS256 signature, JWKS validation1 hour (auto-refresh)
API KeysServer-to-server, SDKs, automationSHA-256 hashing with salt, HMAC signingCustom expiration
# 1. Login to get session cookie
curl -X POST https://pilot.owkai.app/api/auth/token \
-H "Content-Type: application/json" \
-d '{"email": "admin@company.com", "password": "SecurePass123!"}' \
-c cookies.txt

# 2. Use cookie in subsequent requests
curl https://pilot.owkai.app/api/v1/actions \
-b cookies.txt

Quick Start: API Key Authentication

# 1. Generate API key (requires existing session)
curl -X POST https://pilot.owkai.app/api/keys/generate \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{
"name": "Production SDK",
"description": "Production environment API key",
"expires_in_days": 90
}'

# 2. Use API key (returned only once - store securely)
curl https://pilot.owkai.app/api/v1/actions/submit \
-H "X-API-Key: owkai_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"action_type": "database_query",
"target_resource": "users",
"agent_id": "agent-001"
}'

Complete Authentication Guide →

Multi-Tenant Isolation

CRITICAL: All API endpoints enforce organization-level data isolation. Users can ONLY access data belonging to their organization. This is enforced at the database query level using the get_organization_filter() dependency:

# Every database query is automatically filtered
db.query(Model).filter(Model.organization_id == org_id)

Security Guarantees:

  • Cross-tenant data access is impossible at the API layer
  • Organization ID extracted from authenticated user token
  • No manual organization selection - prevents privilege escalation
  • Compliance: SOC 2 CC6.1, PCI-DSS 7.1, HIPAA 164.312(a)

Core API Endpoints

Authentication & Authorization

Prefix: /api/auth

EndpointMethodDescriptionAuth Required
/api/auth/tokenPOSTLogin with email/passwordNo
/api/auth/meGETGet current user profileYes
/api/auth/refresh-tokenPOSTRefresh session tokenYes
/api/auth/logoutPOSTLogout (invalidates all tokens)Yes
/api/auth/csrfGETGet CSRF token for state-changing requestsYes
/api/auth/change-passwordPOSTChange current user passwordYes
/api/auth/forgot-passwordPOSTRequest password reset emailNo
/api/auth/confirm-reset-passwordPOSTComplete password reset with codeNo
/api/auth/cognito-sessionPOSTCreate session from Cognito tokensNo
/api/auth/mfa-statusGETCheck MFA enrollment statusYes
/api/auth/mfa/setup-totpPOSTGenerate TOTP secret and QR codeYes
/api/auth/mfa/verify-totpPOSTVerify TOTP code to complete enrollmentYes
/api/auth/mfa/disablePOSTDisable MFA for current userYes
/api/auth/revoke-tokensPOSTRevoke all user tokens (self)Yes
/api/auth/admin/revoke-user-tokens/{user_id}POSTAdmin: Revoke user tokensAdmin
/api/auth/admin/revoke-organization-tokens/{org_id}POSTPlatform Admin: Revoke org tokensPlatform Admin

Source: routes/auth.py


Agent Actions & Governance

Prefix: /api/v1/actions

EndpointMethodDescriptionAuth Required
/api/v1/actions/submitPOSTSubmit agent action for governance evaluationYes (Cookie/Cognito/API Key)
/api/v1/actionsGETList agent actions for organizationYes
/api/v1/actions/{action_id}GETGet action detailsYes
/api/v1/actions/{action_id}/statusGETGet action statusYes
/api/v1/actions/{action_id}/approvePOSTApprove pending actionYes
/api/v1/actions/{action_id}/rejectPOSTReject pending actionYes
/api/v1/actions/{action_id}/false-positivePOSTMark as false positive (retrains ML)Yes
/api/audit-trailGETComplete audit trail with filtersYes
/api/modelsGETList available AI modelsYes
/api/support/submitPOSTSubmit support ticketYes
/api/v1/actions/upload-jsonPOSTBulk upload actions from JSONYes

Example: Submit Agent Action

curl -X POST https://pilot.owkai.app/api/v1/actions/submit \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{
"action_type": "database_query",
"target_resource": "users",
"agent_id": "agent-prod-001",
"risk_category": "data_access",
"justification": "Fetch user data for analytics dashboard",
"metadata": {
"query": "SELECT * FROM users WHERE created_at > NOW() - INTERVAL 7 DAY",
"database": "production_db"
}
}'

Response:

{
"id": 12345,
"action_id": "act_abc123xyz",
"status": "pending_approval",
"risk_score": 72,
"requires_approval": true,
"policy_evaluation": {
"matched_policies": ["POL-001: Production DB Access"],
"decision": "deny_pending_approval",
"risk_level": "high"
},
"created_at": "2025-12-04T10:30:00Z"
}

Source: routes/agent_routes.py


Authorization & Approvals

Prefix: /api/authorization

EndpointMethodDescriptionAuth Required
/api/authorization/pending-actionsGETList pending approval requestsYes
/api/authorization/authorize/{action_id}POSTApprove/reject actionAdmin
/api/authorization/authorize-with-audit/{action_id}POSTApprove with audit trailAdmin
/api/authorization/dashboardGETApproval dashboard metricsYes
/api/authorization/execution-historyGETAction execution historyYes
/api/authorization/policies/create-from-natural-languagePOSTCreate policy from natural languageAdmin
/api/authorization/policies/{policy_id}/deployPOSTDeploy policy versionAdmin
/api/authorization/policies/{policy_id}/rollback/{version_id}POSTRollback policy to versionAdmin
/api/authorization/mcp-discovery/scan-networkPOSTDiscover MCP servers on networkAdmin
/api/authorization/mcp-discovery/server-statusGETMCP server health statusYes
/api/authorization/mcp-discovery/health-monitorGETReal-time health monitoringYes
/api/authorization/debug/policiesGETDebug policy evaluationAdmin

Source: routes/authorization_routes.py


Automation Playbooks & Workflows

Prefix: /api/authorization/automation, /api/authorization/orchestration

EndpointMethodDescriptionAuth Required
/api/authorization/automation/playbooksGETList automation playbooksYes
/api/authorization/automation/playbooksPOSTCreate playbookAdmin
/api/authorization/automation/playbook/{playbook_id}/togglePOSTEnable/disable playbookAdmin
/api/authorization/automation/execute-playbookPOSTExecute playbookYes
/api/authorization/automation/playbooks/{playbook_id}/testPOSTTest playbook in dry-run modeAdmin
/api/authorization/automation/playbook-templatesGETList playbook templatesYes
/api/authorization/automation/playbook/{playbook_id}DELETEDelete playbookAdmin
/api/authorization/automation/playbook/{playbook_id}/restorePOSTRestore deleted playbookAdmin
/api/authorization/automation/playbooks/deletedGETList deleted playbooksAdmin
/api/authorization/automation/playbook/{playbook_id}/permanentDELETEPermanently delete playbookAdmin
/api/authorization/automation/playbooks/{playbook_id}/versionsGETList playbook versionsYes
/api/authorization/automation/playbooks/{playbook_id}/versionsPOSTCreate new versionAdmin
/api/authorization/automation/playbooks/{playbook_id}/rollbackPOSTRollback to versionAdmin
/api/authorization/automation/playbooks/{playbook_id}/analyticsGETPlaybook analyticsYes
/api/authorization/automation/playbooks/{playbook_id}/performanceGETPerformance metricsYes
/api/authorization/automation/playbooks/clonePOSTClone playbookAdmin
/api/authorization/orchestration/active-workflowsGETList active workflowsYes
/api/authorization/workflows/createPOSTCreate workflowAdmin
/api/authorization/workflowsGETList workflowsYes
/api/authorization/workflow-configGETGet workflow configurationAdmin
/api/authorization/workflow-configPOSTUpdate workflow configurationAdmin
/api/authorization/orchestration/execute/{workflow_id}POSTExecute workflowYes
/api/authorization/automation/activity-feedGETAutomation activity feedYes

Source: routes/automation_orchestration_routes.py, routes/playbook_deletion_routes.py, routes/playbook_versioning_routes.py, routes/enterprise_workflow_config_routes.py


Unified Governance & Policies

Prefix: /api (various governance endpoints)

EndpointMethodDescriptionAuth Required
/api/unified/actionPOSTSubmit unified governance actionYes
/api/unified-statsGETUnified governance statisticsYes
/api/unified-actionsGETList unified actionsYes
/api/unified/actionsGETAlternative unified actions endpointYes
/api/policiesGETList all policiesYes
/api/create-policyPOSTCreate new policyAdmin
/api/policies/{policy_id}PUTUpdate policyAdmin
/api/policies/{policy_id}DELETEDelete policyAdmin
/api/policies/{policy_id}/check-conflictsPOSTCheck for policy conflictsAdmin
/api/policies/conflicts/analyzeGETAnalyze all policy conflictsAdmin
/api/policies/exportGETExport policiesAdmin
/api/policies/importPOSTImport policiesAdmin
/api/policies/import/templateGETGet import templateAdmin
/api/policies/backupPOSTBackup policiesAdmin
/api/policies/bulk-update-statusPOSTBulk update policy statusAdmin
/api/policies/bulk-deletePOSTBulk delete policiesAdmin
/api/policies/bulk-update-priorityPOSTBulk update policy priorityAdmin
/api/policies/templatesGETList policy templatesYes
/api/policies/from-templatePOSTCreate policy from templateAdmin
/api/policies/dashboard/pending-approvalsGETPending approvals dashboardYes
/api/healthGETGovernance health checkYes
/api/admin/unified-reportGETAdmin unified governance reportAdmin

Source: routes/unified_governance_routes.py


MCP (Model Context Protocol) Governance

Prefix: /api/mcp

EndpointMethodDescriptionAuth Required
/api/mcp/evaluatePOSTEvaluate MCP action against policiesYes
/api/mcp/executePOSTExecute approved MCP actionYes
/api/mcp/servers/registerPOSTRegister MCP serverAdmin
/api/mcp/serversGETList registered MCP serversYes
/api/mcp/actions/pendingGETList pending MCP actionsYes
/api/mcp/actions/{action_id}/approvePOSTApprove MCP actionAdmin
/api/mcp/actions/allGETList all MCP actionsYes
/api/mcp/policiesPOSTCreate MCP policyAdmin
/api/mcp/policiesGETList MCP policiesYes
/api/mcp/analytics/dashboardGETMCP analytics dashboardYes
/api/mcp/healthGETMCP system healthYes
/api/mcp/test/evaluatePOSTTest MCP policy evaluationAdmin
/api/mcp/actions/assess-risk-enterprisePOSTEnterprise risk assessmentYes
/api/mcp/actionsGETList MCP actionsYes
/api/mcp/actions/ingestPOSTIngest MCP actionsYes

Source: routes/mcp_governance_routes.py, routes/mcp_enterprise_secure.py, routes/mcp_governance_adapter.py


Agent Registry & Health

Prefix: /api/registry, /api/agents/health

EndpointMethodDescriptionAuth Required
/api/registry/agentsPOSTRegister new agentAdmin
/api/registry/agentsGETList registered agentsYes
/api/registry/agents/{agent_id}GETGet agent detailsYes
/api/registry/agents/{agent_id}PUTUpdate agentAdmin
/api/registry/agents/{agent_id}DELETEDelete agentAdmin
/api/registry/agents/{agent_id}/activatePOSTActivate agentAdmin
/api/registry/agents/{agent_id}/suspendPOSTSuspend agentAdmin
/api/registry/agents/{agent_id}/emergency-suspendPOSTEmergency suspend agentAdmin
/api/registry/agents/{agent_id}/versionsGETList agent versionsYes
/api/registry/agents/{agent_id}/rollbackPOSTRollback to versionAdmin
/api/registry/agents/{agent_id}/policiesPOSTAttach policy to agentAdmin
/api/registry/agents/{agent_id}/policiesGETList agent policiesYes
/api/registry/agents/{agent_id}/evaluatePOSTEvaluate agent behaviorAdmin
/api/registry/agents/{agent_id}/usageGETAgent usage statisticsYes
/api/registry/agents/{agent_id}/anomaliesGETDetect agent anomaliesYes
/api/registry/agents/{agent_id}/rate-limitsPUTUpdate rate limitsAdmin
/api/registry/agents/{agent_id}/budgetPUTUpdate cost budgetAdmin
/api/registry/agents/{agent_id}/time-windowPUTUpdate time window limitsAdmin
/api/registry/agents/{agent_id}/escalationPUTUpdate escalation configAdmin
/api/registry/agents/{agent_id}/auto-suspendPUTConfigure auto-suspendAdmin
/api/registry/agents/{agent_id}/data-classificationsPUTSet data classificationsAdmin
/api/registry/agents/{agent_id}/set-baselinesPOSTSet performance baselinesAdmin
/api/registry/mcp-serversPOSTRegister MCP serverAdmin
/api/registry/mcp-serversGETList MCP serversYes
/api/registry/mcp-servers/{server_name}GETGet MCP server detailsYes
/api/registry/mcp-servers/{server_name}PUTUpdate MCP serverAdmin
/api/registry/mcp-servers/{server_name}DELETEDelete MCP serverAdmin
/api/registry/mcp-servers/{server_name}/activatePOSTActivate MCP serverAdmin
/api/registry/mcp-servers/{server_name}/deactivatePOSTDeactivate MCP serverAdmin
/api/agents/health/heartbeatPOSTSubmit agent heartbeatYes
/api/agents/health/heartbeat/batchPOSTSubmit batch heartbeatsYes
/api/agents/health/summaryGETHealth summary for all agentsYes
/api/agents/health/{agent_id}GETHealth status for agentYes
/api/agents/health/{agent_id}/intervalPUTUpdate heartbeat intervalAdmin
/api/agents/health/checkPOSTForce health checkAdmin
/api/agents/health/public/statusGETPublic health status (no auth)No

Source: routes/agent_registry_routes.py, routes/agent_health_routes.py


API Key Management

Prefix: /api/keys

EndpointMethodDescriptionAuth Required
/api/keys/generatePOSTGenerate new API keyAdmin
/api/keys/listGETList API keys for organizationAdmin
/api/keys/{key_id}/revokeDELETERevoke API keyAdmin
/api/keys/{key_id}/usageGETGet API key usage statisticsAdmin

Example: Generate API Key

curl -X POST https://pilot.owkai.app/api/keys/generate \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{
"name": "Production SDK",
"description": "API key for production environment",
"expires_in_days": 90,
"rate_limit": {
"max_requests": 5000,
"window_seconds": 3600
}
}'

Response (Secret shown ONCE - store securely):

{
"success": true,
"api_key": "owkai_admin_tUsL1234567890abcdef",
"key_id": 42,
"key_prefix": "owkai_admin_tUsL",
"name": "Production SDK",
"expires_at": "2026-03-04T10:30:00Z",
"created_at": "2025-12-04T10:30:00Z",
"warning": "⚠️ Save this key now - you will NOT see it again!"
}

Source: routes/api_key_routes.py


Alerts & Insights

Prefix: /api (alert endpoints)

EndpointMethodDescriptionAuth Required
/api/alertsGETList alerts for organizationYes
/api/alerts/countGETGet alert countYes
/api/alerts/{alert_id}PATCHUpdate alert (acknowledge/resolve)Yes
/api/alerts/create-test-dataPOSTCreate test alerts (dev only)Admin
/api/alerts/summaryPOSTGenerate alert summaryYes
/api/alerts/summary-textPOSTGenerate text-based summaryYes
/api/activeGETList active alertsYes
/api/{alert_id}/acknowledgePOSTAcknowledge alertYes
/api/{alert_id}/resolvePOSTResolve alertYes
/api/{alert_id}/escalatePOSTEscalate alertAdmin

Source: routes/alert_routes.py, routes/alert_summary.py, routes/smart_alerts.py


Analytics & Insights

Prefix: /api (analytics endpoints)

EndpointMethodDescriptionAuth Required
/api/analytics/trendsGETAlert trends over timeYes
/api/analytics/realtime/metricsGETReal-time metricsYes
/api/analytics/predictive/trendsGETPredictive analyticsYes
/api/analytics/executive/dashboardGETExecutive dashboardAdmin
/api/analytics/performanceGETPerformance analyticsYes
/api/analytics/performance/systemGETSystem performance metricsYes
/api/analytics/debugGETDebug analytics dataAdmin

WebSocket:

wss://pilot.owkai.app/analytics/ws/realtime/{user_email}

Source: routes/analytics_routes.py


Executive Briefs

Prefix: /api/executive-briefs

EndpointMethodDescriptionAuth Required
/api/executive-briefs/latestGETGet latest executive briefAdmin
/api/executive-briefs/{brief_id}GETGet specific briefAdmin
/api/executive-briefs/generatePOSTGenerate new briefAdmin
/api/executive-briefs/regeneratePOSTForce regenerate briefAdmin
/api/executive-briefs/cooldownGETCheck cooldown statusAdmin
/api/executive-briefs/historyGETBrief generation historyAdmin

Source: routes/executive_brief_routes.py


Rules & Smart Rules

Prefix: /api (rule endpoints)

EndpointMethodDescriptionAuth Required
/api/rulesGETList rulesYes
/api/rulesPOSTCreate ruleAdmin
/api/rules/{rule_id}DELETEDelete ruleAdmin
/api/rules/seedPOSTSeed default rulesAdmin
/api/rules/generate-smart-rulePOSTGenerate smart rule with AIAdmin
/api/feedback/{rule_id}GETGet rule feedbackYes
/api/feedback/{rule_id}POSTSubmit rule feedbackYes
/api/smart-rules/analyticsGETSmart rule analyticsYes
/api/smart-rules/ab-testsGETList A/B testsYes
/api/smart-rules/ab-testPOSTCreate A/B testAdmin
/api/smart-rules/ab-test/{test_id}GETGet A/B test detailsYes
/api/smart-rules/ab-test/{test_id}/stopPOSTStop A/B testAdmin
/api/smart-rules/ab-test/{test_id}/deployPOSTDeploy winning variantAdmin
/api/smart-rules/ab-test/{test_id}DELETEDelete A/B testAdmin
/api/smart-rules/suggestionsGETGet rule suggestionsYes
/api/smart-rules/generate-from-nlPOSTGenerate rule from natural languageAdmin
/api/smart-rules/optimize/{rule_id}POSTOptimize rule with MLAdmin
/api/smart-rules/{rule_id}DELETEDelete smart ruleAdmin
/api/smart-rules/generatePOSTGenerate smart ruleAdmin
/api/smart-rules/seedPOSTSeed default smart rulesAdmin

Source: routes/rule_routes.py, routes/smart_rules_routes.py


Compliance & Audit

Prefix: /api/compliance-export, /api/audit

EndpointMethodDescriptionAuth Required
/api/compliance-export/frameworksGETList compliance frameworksAdmin
/api/compliance-export/frameworks/{framework}GETGet framework detailsAdmin
/api/compliance-export/exportsPOSTCreate export jobAdmin
/api/compliance-export/exportsGETList export jobsAdmin
/api/compliance-export/exports/{job_id}GETGet export job statusAdmin
/api/compliance-export/exports/{job_id}/downloadGETDownload exportAdmin
/api/compliance-export/exports/{job_id}/downloadsGETList downloads for jobAdmin
/api/compliance-export/exports/{job_id}/verifyPOSTVerify export integrityAdmin
/api/compliance-export/schedulesPOSTCreate export scheduleAdmin
/api/compliance-export/schedulesGETList schedulesAdmin
/api/compliance-export/schedules/{schedule_id}GETGet schedule detailsAdmin
/api/compliance-export/schedules/{schedule_id}PUTUpdate scheduleAdmin
/api/compliance-export/schedules/{schedule_id}DELETEDelete scheduleAdmin
/api/compliance-export/quick-export/{framework}/{report_type}POSTQuick exportAdmin
/api/compliance-export/metricsGETCompliance metricsAdmin
/api/audit/healthGETAudit system healthAdmin
/api/audit/logPOSTSubmit audit log entryYes
/api/audit/logsGETQuery audit logsAdmin
/api/audit/verify-integrityPOSTVerify audit log integrityAdmin
/api/audit/export/csvGETExport audit logs as CSVAdmin
/api/audit/export/pdfGETExport audit logs as PDFAdmin

Supported Compliance Frameworks:

  • SOC 2 Type II
  • PCI-DSS
  • HIPAA
  • GDPR
  • SOX
  • ISO 27001
  • NIST 800-53
  • CCPA

Source: routes/compliance_export_routes.py, routes/audit_routes.py


Data Rights (GDPR/CCPA)

Prefix: /api/data-rights

EndpointMethodDescriptionAuth Required
/api/data-rights/access/requestPOSTRequest data access (GDPR Art. 15)Yes
/api/data-rights/access/{request_id}/dataGETDownload data access requestYes
/api/data-rights/erasure/requestPOSTRequest data erasure (GDPR Art. 17)Yes
/api/data-rights/erasure/{request_id}/executePOSTExecute erasure requestAdmin
/api/data-rights/portability/requestPOSTRequest data portability (GDPR Art. 20)Yes
/api/data-rights/consent/recordPOSTRecord consentYes
/api/data-rights/lineage/recordPOSTRecord data lineageYes
/api/data-rights/lineage/subject/{subject_identifier}GETGet data lineageAdmin
/api/data-rights/compliance/reportGETCompliance reportAdmin
/api/data-rights/requestsGETList data rights requestsAdmin
/api/data-rights/requests/{request_id}GETGet request detailsYes
/api/data-rights/healthGETData rights system healthAdmin

Source: routes/data_rights_routes.py


Enterprise Integrations

Prefix: /api/integrations

EndpointMethodDescriptionAuth Required
/api/integrations/typesGETList integration typesYes
/api/integrations/templatesGETList integration templatesYes
/api/integrations/statusGETIntegration statusYes
/api/integrations/{integration_id}GETGet integration detailsYes
/api/integrations/{integration_id}PUTUpdate integrationAdmin
/api/integrations/{integration_id}DELETEDelete integrationAdmin
/api/integrations/health/summaryGETHealth summary for all integrationsYes
/api/integrations/{integration_id}/health-checkPOSTRun health checkAdmin
/api/integrations/{integration_id}/health-historyGETHealth check historyYes
/api/integrations/data-flowsPOSTCreate data flowAdmin
/api/integrations/data-flows/from-templatePOSTCreate from templateAdmin
/api/integrations/data-flowsGETList data flowsYes
/api/integrations/data-flows/{data_flow_id}/executePOSTExecute data flowAdmin
/api/integrations/eventsGETList integration eventsYes
/api/integrations/events/correlatePOSTCorrelate eventsAdmin
/api/integrations/dashboardGETIntegration dashboardYes
/api/integrations/metricsGETIntegration metricsYes
/api/integrations/bulkPOSTBulk create integrationsAdmin
/api/integrations/testPOSTTest integrationAdmin

Integration Wizard:

EndpointMethodDescriptionAuth Required
/api/integrations/wizard/typesGETList integration typesYes
/api/integrations/wizard/types/{type_id}GETGet type detailsYes
/api/integrations/wizard/code-snippets/{type_id}GETGet code snippetsYes
/api/integrations/wizard/checklist/{type_id}GETGet setup checklistYes
/api/integrations/wizard/quick-startGETQuick start guideYes
/api/integrations/wizard/validate-configPOSTValidate configurationAdmin

Source: routes/integration_suite_routes.py, routes/integration_wizard_routes.py


SIEM Integration

Prefix: /api/siem-integration

EndpointMethodDescriptionAuth Required
/api/siem-integration/statusGETSIEM integration statusAdmin
/api/siem-integration/configurePOSTConfigure SIEM connectionAdmin
/api/siem-integration/test-connectionPOSTTest SIEM connectionAdmin
/api/siem-integration/send-eventPOSTSend event to SIEMYes
/api/siem-integration/forward-authorization/{action_id}POSTForward authorization eventYes
/api/siem-integration/threat-intelligencePOSTSend threat intelligenceYes
/api/siem-integration/query-eventsGETQuery SIEM eventsAdmin
/api/siem-integration/metricsGETSIEM integration metricsAdmin
/api/siem-integration/bulk-forwardPOSTBulk forward eventsAdmin
/api/siem-integration/healthGETSIEM health checkAdmin

Supported SIEM Platforms:

  • Splunk
  • Datadog
  • Wiz
  • QRadar
  • ArcSight
  • LogRhythm

Simplified SIEM API:

EndpointMethodDescriptionAuth Required
/api/enterprise/siem/configurePOSTConfigure SIEMAdmin
/api/enterprise/siem/test-connectionPOSTTest connectionAdmin
/api/enterprise/siem/statusGETConnection statusAdmin
/api/enterprise/siem/send-test-eventPOSTSend test eventAdmin
/api/enterprise/siem/supported-integrationsGETList supported platformsYes
/api/enterprise/siem/disconnectDELETEDisconnect SIEMAdmin

Source: routes/siem_integration.py, routes/siem_simple.py


ServiceNow Integration

Prefix: /api/servicenow

EndpointMethodDescriptionAuth Required
/api/servicenow/connectionsPOSTCreate ServiceNow connectionAdmin
/api/servicenow/connectionsGETList connectionsAdmin
/api/servicenow/connections/{connection_id}GETGet connection detailsAdmin
/api/servicenow/connections/{connection_id}PUTUpdate connectionAdmin
/api/servicenow/connections/{connection_id}DELETEDelete connectionAdmin
/api/servicenow/connections/{connection_id}/testPOSTTest connectionAdmin
/api/servicenow/ticketsPOSTCreate ServiceNow ticketYes
/api/servicenow/ticketsGETList ticketsYes
/api/servicenow/tickets/{ticket_id}GETGet ticket detailsYes
/api/servicenow/tickets/{ticket_id}PUTUpdate ticketAdmin
/api/servicenow/tickets/{ticket_id}/retryPOSTRetry failed ticket creationAdmin
/api/servicenow/event-mappingsGETList event mappingsAdmin
/api/servicenow/metricsGETServiceNow metricsAdmin
/api/servicenow/sync-logsGETSync logsAdmin

Source: routes/servicenow_routes.py


Webhooks

Prefix: /api/webhooks

EndpointMethodDescriptionAuth Required
/api/webhooks/eventsGETList available webhook event typesYes
/api/webhooksPOSTCreate webhook subscriptionAdmin
/api/webhooksGETList subscriptionsAdmin
/api/webhooks/{subscription_id}GETGet subscription detailsAdmin
/api/webhooks/{subscription_id}PUTUpdate subscriptionAdmin
/api/webhooks/{subscription_id}DELETEDelete subscriptionAdmin
/api/webhooks/{subscription_id}/rotate-secretPOSTRotate webhook secretAdmin
/api/webhooks/{subscription_id}/testPOSTSend test webhookAdmin
/api/webhooks/{subscription_id}/deliveriesGETList deliveries for subscriptionAdmin
/api/webhooks/dlq/entriesGETList dead letter queue entriesAdmin
/api/webhooks/dlq/{dlq_id}/resolvePOSTResolve DLQ entryAdmin
/api/webhooks/dlq/{dlq_id}/retryPOSTRetry DLQ entryAdmin
/api/webhooks/metricsGETWebhook metricsAdmin

Supported Webhook Events:

  • action.submitted
  • action.approved
  • action.rejected
  • action.executed
  • action.failed
  • policy.created
  • policy.updated
  • policy.deleted
  • policy.violated
  • alert.triggered
  • alert.resolved
  • alert.escalated
  • risk.threshold_exceeded
  • risk.score_changed
  • compliance.report_ready
  • compliance.violation
  • user.login
  • user.logout
  • user.mfa_enabled
  • system.health_alert

Complete Webhook Documentation →

Source: routes/webhook_routes.py


Notifications

Prefix: /api/notifications

EndpointMethodDescriptionAuth Required
/api/notifications/eventsGETList notification eventsYes
/api/notifications/channelsPOSTCreate notification channelAdmin
/api/notifications/channelsGETList channelsAdmin
/api/notifications/channels/{channel_id}GETGet channel detailsAdmin
/api/notifications/channels/{channel_id}PUTUpdate channelAdmin
/api/notifications/channels/{channel_id}DELETEDelete channelAdmin
/api/notifications/channels/{channel_id}/testPOSTTest channelAdmin
/api/notifications/channels/{channel_id}/pausePOSTPause channelAdmin
/api/notifications/channels/{channel_id}/resumePOSTResume channelAdmin
/api/notifications/channels/{channel_id}/deliveriesGETList deliveriesAdmin
/api/notifications/deliveriesGETList all deliveriesAdmin
/api/notifications/metricsGETNotification metricsAdmin
/api/notifications/sendPOSTSend notificationAdmin

Supported Channels:

  • Email
  • SMS
  • Slack
  • Microsoft Teams
  • Webhook

Source: routes/notification_routes.py


Risk Configuration

Prefix: /api/risk-scoring

EndpointMethodDescriptionAuth Required
/api/risk-scoring/configGETGet current risk configurationAdmin
/api/risk-scoring/config/historyGETConfiguration historyAdmin
/api/risk-scoring/configPOSTCreate risk configurationAdmin
/api/risk-scoring/config/{config_id}/activatePUTActivate configurationAdmin
/api/risk-scoring/config/validatePOSTValidate configurationAdmin
/api/risk-scoring/config/rollback-to-defaultPOSTRollback to default configAdmin

Source: routes/risk_scoring_config_routes.py


User Management

Prefix: /api/admin, /api/enterprise-users

Admin Console Users:

EndpointMethodDescriptionAuth Required
/api/admin/organizationGETGet organization detailsAdmin
/api/admin/organizationPATCHUpdate organizationAdmin
/api/admin/usersGETList usersAdmin
/api/admin/users/invitePOSTInvite userAdmin
/api/admin/users/{user_id}/rolePATCHUpdate user roleAdmin
/api/admin/users/{user_id}DELETEDelete userAdmin
/api/admin/users/{user_id}/suspendPATCHSuspend/unsuspend userAdmin
/api/admin/users/{user_id}/profilePATCHUpdate user profileAdmin
/api/admin/users/{user_id}/reset-passwordPOSTReset user passwordAdmin
/api/admin/users/{user_id}/force-logoutPOSTForce user logoutAdmin
/api/admin/users/{user_id}/activityGETUser activity logAdmin
/api/admin/users/bulk-operationPOSTBulk user operationsAdmin
/api/admin/rbac/levelsGETList RBAC levelsAdmin
/api/admin/rbac/usersGETList users with RBACAdmin
/api/admin/users/{user_id}/access-levelPATCHUpdate access levelAdmin

Enterprise User Management:

EndpointMethodDescriptionAuth Required
/api/enterprise-users/usersGETList usersAdmin
/api/enterprise-users/usersPOSTCreate userAdmin
/api/enterprise-users/users/{user_id}PUTUpdate userAdmin
/api/enterprise-users/users/{user_id}DELETEDelete userAdmin
/api/enterprise-users/users/{user_id}/reset-passwordPOSTReset passwordAdmin
/api/enterprise-users/users/{user_id}/unlockPOSTUnlock accountAdmin
/api/enterprise-users/rolesGETList rolesAdmin
/api/enterprise-users/rolesPOSTCreate roleAdmin
/api/enterprise-users/roles/{role_id}PUTUpdate roleAdmin
/api/enterprise-users/audit-logsGETUser audit logsAdmin
/api/enterprise-users/analyticsGETUser analyticsAdmin

Source: routes/admin_console_routes.py, routes/enterprise_user_management_routes.py, routes/admin_routes.py


Secret Rotation

Prefix: /api/secrets

EndpointMethodDescriptionAuth Required
/api/secrets/statusGETRotation status for all secretsAdmin
/api/secrets/rotatePOSTRotate specific secretAdmin
/api/secrets/rotate-allPOSTRotate all secretsAdmin
/api/secrets/schedulePOSTSchedule rotationAdmin
/api/secrets/schedulesGETList rotation schedulesAdmin
/api/secrets/schedule/{secret_name}DELETEDelete scheduleAdmin
/api/secrets/compliance-reportGETCompliance reportAdmin
/api/secrets/audit-trailGETRotation audit trailAdmin
/api/secrets/rotation-historyGETRotation historyAdmin
/api/secrets/emergency-rotationPOSTEmergency rotationAdmin
/api/secrets/validate-secretsPOSTValidate secretsAdmin
/api/secrets/healthGETSecret rotation system healthAdmin

Source: routes/enterprise_secrets_routes.py


Retention Policies

Prefix: /api/retention

EndpointMethodDescriptionAuth Required
/api/retention/healthGETRetention system healthAdmin
/api/retention/statisticsGETRetention statisticsAdmin
/api/retention/backfillPOSTBackfill retention metadataAdmin
/api/retention/expiredGETList expired itemsAdmin
/api/retention/cleanupPOSTRun cleanup jobAdmin
/api/retention/legal-holdPOSTApply legal holdAdmin
/api/retention/legal-hold/releasePOSTRelease legal holdAdmin
/api/retention/job-statusGETCleanup job statusAdmin
/api/retention/trigger-manual-cleanupPOSTTrigger manual cleanupAdmin

Source: routes/retention_routes.py


Organization Administration

Prefix: /api/organizations

EndpointMethodDescriptionAuth Required
/api/organizations/{org_id}/usersPOSTCreate user in organizationAdmin
/api/organizations/{org_id}/usersGETList users in organizationAdmin
/api/organizations/{org_id}/users/{user_id}DELETEDelete userAdmin
/api/organizations/{org_id}/users/{user_id}/rolePATCHUpdate user roleAdmin
/api/organizations/{org_id}/subscription-infoGETGet subscription infoAdmin
/api/organizations/usersPOSTCreate user (current org)Admin
/api/organizations/usersGETList users (current org)Admin
/api/organizations/users/{user_id}DELETEDelete user (current org)Admin
/api/organizations/users/{user_id}/rolePATCHUpdate role (current org)Admin
/api/organizations/subscription-infoGETGet subscription (current org)Admin

Source: routes/organization_admin_routes.py


Platform Administration

Prefix: /api/platform

EndpointMethodDescriptionAuth Required
/api/platform/organizationsGETList all organizationsPlatform Admin
/api/platform/organizationsPOSTCreate organizationPlatform Admin
/api/platform/organizations/{org_id}GETGet organization detailsPlatform Admin
/api/platform/usage-statsGETPlatform usage statisticsPlatform Admin
/api/platform/actionsGETAll actions across platformPlatform Admin
/api/platform/high-risk-actionsGETHigh-risk actionsPlatform Admin
/api/platform/auth-audit-logGETAuthentication audit logPlatform Admin
/api/platform/brute-force-attemptsGETBrute force attemptsPlatform Admin
/api/platform/active-tokensGETActive authentication tokensPlatform Admin

Source: routes/platform_admin_routes.py


Self-Service Signup

Prefix: /api/signup

EndpointMethodDescriptionAuth Required
/api/signup/requestPOSTRequest organization signupNo
/api/signup/verify-emailPOSTVerify email addressNo
/api/signup/resend-verificationPOSTResend verification emailNo
/api/signup/status/{signup_id}GETCheck signup statusNo

Source: routes/signup_routes.py


AWS Cognito Pool Management

Prefix: /api/cognito

EndpointMethodDescriptionAuth Required
/api/cognito/pool-config/by-slug/{organization_slug}GETGet pool config by slugAdmin
/api/cognito/pool-config/by-id/{organization_id}GETGet pool config by org IDAdmin
/api/cognito/pool-config/by-email/{email}GETGet pool config by emailNo
/api/cognito/pool-status/{organization_slug}GETGet pool statusAdmin
/api/cognito/organizationsGETList organizations with poolsAdmin
/api/cognito/healthGETCognito integration healthAdmin

Source: routes/cognito_pool_routes.py


SDK & Agent Integration

Prefix: /api/sdk

EndpointMethodDescriptionAuth Required
/api/sdk/agent/registerPOSTRegister agent with SDKAPI Key
/api/sdk/action/{action_id}/completedPOSTMark action completedAPI Key
/api/sdk/action/{action_id}/failedPOSTMark action failedAPI Key
/api/sdk/approval/{approval_id}GETCheck approval statusAPI Key
/api/sdk/webhooks/configurePOSTConfigure SDK webhooksAPI Key
/api/sdk/healthGETSDK health checkAPI Key

Source: routes/sdk_routes.py


Diagnostics & Health

Prefix: /api/diagnostics

EndpointMethodDescriptionAuth Required
/api/diagnostics/healthGETOverall system healthAdmin
/api/diagnostics/apiGETAPI health checkAdmin
/api/diagnostics/databaseGETDatabase health checkAdmin
/api/diagnostics/integrationsGETIntegration health checkAdmin
/api/diagnostics/historyGETDiagnostic historyAdmin
/api/diagnostics/exportPOSTExport diagnosticsAdmin

Source: routes/diagnostics_routes.py


Documentation

Prefix: /api/docs

EndpointMethodDescriptionAuth Required
/api/docs/integrationGETIntegration documentationYes
/api/docs/integration/readmeGETREADME documentationYes
/api/docs/integration/risk-scoringGETRisk scoring guideYes
/api/docs/integration/api-referenceGETAPI referenceYes
/api/docs/integration/sdk-guideGETSDK guideYes
/api/docs/integration/architectureGETArchitecture documentationYes
/api/docs/integration/agent-registryGETAgent registry docsYes
/api/docs/integration/agent-governanceGETAgent governance docsYes
/api/docs/integration/governance-controlsGETGovernance controls docsYes
/api/docs/integration/{doc_name}GETGet specific documentYes
/api/docs/quick-startGETQuick start guideYes
/api/docs/action-typesGETList action typesYes

Source: routes/docs_routes.py


System Health & Info

EndpointMethodDescriptionAuth Required
/healthGETSystem health checkNo
/api/deployment-infoGETDeployment information (commit SHA, build date)No
/api/modelsGETList available AI modelsYes
/api/logsGETSystem logsAdmin
/api/security-findingsGETSecurity findingsAdmin

Source: routes/main_routes.py, main.py


Rate Limits & Quotas

Default Rate Limits

Auth MethodRequests/MinuteRequests/HourRequests/Day
Cookie Session1006,000100,000
Cognito JWT1006,000100,000
API Key (default)1,00060,0001,000,000
API Key (custom)ConfigurableConfigurableConfigurable

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1733308800
X-RateLimit-Retry-After: 45

Brute Force Protection

Protection TypeThresholdWindowLockout Duration
IP-based login attempts5 failures15 minutes15 minutes
Email-based login attempts10 failures15 minutesExponential (up to 24 hours)
API key brute force20 failures5 minutes1 hour
Password reset attempts5 requests1 hour1 hour

Error Handling

Standard Error Response

{
"detail": "Error message",
"error_code": "ERR_CODE",
"request_id": "req_abc123xyz",
"timestamp": "2025-12-04T10:30:00Z",
"path": "/api/v1/actions"
}

HTTP Status Codes

CodeMeaningDescription
200OKRequest successful
201CreatedResource created successfully
204No ContentRequest successful, no content to return
400Bad RequestInvalid request parameters
401UnauthorizedMissing or invalid authentication
403ForbiddenInsufficient permissions or cross-tenant access attempt
404Not FoundResource not found or not accessible
409ConflictResource conflict (e.g., duplicate)
422Unprocessable EntityValidation error
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error
503Service UnavailableService temporarily unavailable

Common Error Codes

CodeDescription
AUTH_001Invalid credentials
AUTH_002Token expired
AUTH_003Insufficient permissions
AUTH_004MFA required
AUTH_005Account locked
TENANT_001Cross-tenant access denied
RATE_001Rate limit exceeded
POLICY_001Policy violation
VALIDATION_001Invalid input

Security Best Practices

1. Authentication

  • Web Apps: Use cookie-based sessions with CSRF protection
  • Mobile Apps: Use AWS Cognito JWT with secure token storage
  • Server-to-Server: Use API keys with minimal required permissions
  • All Environments: Enable MFA for admin accounts

2. API Key Security

  • Store API keys in environment variables or secure vaults (AWS Secrets Manager, HashiCorp Vault)
  • Never commit API keys to version control
  • Rotate API keys every 90 days (or per your security policy)
  • Use separate API keys for dev/staging/production
  • Revoke API keys immediately if compromised

3. Request Security

  • Always use HTTPS (TLS 1.3)
  • Include CSRF token for state-changing requests (POST, PUT, DELETE, PATCH)
  • Validate all input on client and server side
  • Sanitize output to prevent XSS
  • Use parameterized queries to prevent SQL injection

4. Data Security

  • Never include sensitive data in URLs (use request body)
  • Encrypt sensitive data at rest and in transit
  • Implement proper access controls (RBAC)
  • Audit all data access and modifications
  • Follow principle of least privilege

5. Monitoring & Logging

  • Monitor API usage for anomalies
  • Set up alerts for unusual activity
  • Review audit logs regularly
  • Track API key usage
  • Implement automated security scanning

Compliance & Governance

Regulatory Compliance

Ascend Platform API is compliant with:

  • SOC 2 Type II - Security, availability, confidentiality
  • PCI-DSS - Payment card industry data security
  • HIPAA - Healthcare information privacy
  • GDPR - EU data protection and privacy
  • SOX - Financial reporting integrity
  • ISO 27001 - Information security management
  • NIST 800-53 - Federal information security controls
  • CCPA - California consumer privacy

Data Residency

  • US Region: us-east-2 (Ohio)
  • EU Region: eu-west-1 (Ireland) - Coming Soon
  • APAC Region: ap-southeast-1 (Singapore) - Coming Soon

Audit Trail

All API requests are logged with:

  • Timestamp
  • User/API key identity
  • Organization ID
  • IP address
  • Request method and endpoint
  • Request/response payloads (configurable)
  • Response status code
  • Processing duration

Audit logs are immutable and retained per your compliance requirements (default: 7 years).


Webhook Events

Subscribe to real-time events via webhooks. See Webhook Documentation for complete details.

Available Events:

CategoryEvents
Agent Actionsaction.submitted, action.approved, action.rejected, action.executed, action.failed
Policiespolicy.created, policy.updated, policy.deleted, policy.violated
Alertsalert.triggered, alert.resolved, alert.escalated
Riskrisk.threshold_exceeded, risk.score_changed
Compliancecompliance.report_ready, compliance.violation
Usersuser.login, user.logout, user.mfa_enabled
Systemsystem.health_alert

API Versioning

The Ascend API uses URL-based versioning:

Current Version: v1 (implicit in all /api/* endpoints)
Future Versions: /api/v2/* (when available)

Versioning Policy:

  • Current version supported for minimum 24 months after new version release
  • Breaking changes require new version
  • Deprecation notices given 6 months in advance
  • Security patches backported to all supported versions

Support & Resources

Documentation

API Status

Support Channels

SLA Guarantees

PlanUptime SLASupport Response Time
Enterprise99.99%< 1 hour (24/7)
Professional99.9%< 4 hours (business hours)
Standard99.5%< 24 hours (business hours)

API Change Log

2025-12-04 (Current)

  • SEC-081: Documentation rewrite with verified endpoints only
  • 564 endpoints across 54 route modules documented
  • Added comprehensive security, compliance, and best practices sections

2025-12-03

  • SEC-066: Unified Metrics Architecture implementation
  • Added Executive Brief endpoints
  • Added Metric Audit Trail endpoints

2025-11-30

  • SEC-025: Multi-tenant email system
  • Agent Registry endpoints
  • Agent Health endpoints

2025-11-28

  • Enterprise Webhook System (HMAC-SHA256 signed webhooks)
  • ServiceNow Integration
  • Notification Channels
  • Compliance Export System

2025-11-26

  • SEC-007: Multi-tenant data isolation (CRITICAL)
  • Organization filter dependency across all endpoints
  • Banking-level security implementation

Document Information:

  • Document ID: SEC-081-API-OVERVIEW
  • Version: 2.0.0
  • Last Updated: 2025-12-04
  • Verification: All 564 endpoints verified from source code (54 route files)
  • Compliance: SOC 2, PCI-DSS, HIPAA, GDPR, SOX