Skip to Content
API & ContractsCore Endpoints

Core Endpoints

This page highlights commonly used API groups. Use the generated API reference for the exhaustive operation and schema index.

Cluster APIs

  • GET /api/v1/clusters
  • POST /api/v1/clusters
  • GET /api/v1/clusters/capabilities
  • GET /api/v1/clusters/:clusterID/detail
  • GET /api/v1/clusters/:clusterID/namespaces
  • GET /api/v1/clusters/:clusterID/infrastructure/nodes
  • GET /api/v1/clusters/:clusterID/workloads/pods?namespace=default
  • GET /api/v1/clusters/:clusterID/workloads/deployments?namespace=default
  • GET /api/v1/clusters/:clusterID/workloads/statefulsets?namespace=<optional>
  • GET /api/v1/clusters/:clusterID/network/services?namespace=<optional>
  • GET /api/v1/clusters/:clusterID/network/ingresses?namespace=<optional>
  • GET /api/v1/clusters/:clusterID/events?namespace=<optional>&limit=20
  • POST /api/v1/clusters/:clusterID/workloads/deployments/restart
  • POST /api/v1/clusters/:clusterID/workloads/deployments/scale

/clusters/capabilities returns the Direct/Agent runtime capability matrix consumed by Console, CLI, Skills, and external integrations. Each entry includes the capability key, category, required scopes, risk level, approval expectation, documentation URL, and separate Direct/Agent support status with reasons for partial or unsupported modes.

Audit APIs

  • GET /api/v1/audit/logs

Monitoring APIs

  • POST /api/v1/integrations/alerts/webhook
  • GET /api/v1/monitoring/summary
  • GET /api/v1/alerts?status=<optional>&clusterId=<optional>&limit=50
  • GET /api/v1/notification-channels
  • POST /api/v1/notification-channels
  • PUT /api/v1/notification-channels/:channelID

AI Settings APIs

  • GET /api/v1/settings/ai
  • PUT /api/v1/settings/ai/workbench-model
  • PUT /api/v1/settings/ai/skills

Virtualization APIs

The public contract covers connection, VM, image, flavor, operation, metrics, console, synchronization, cancellation, and retry routes. Use the generated API reference for the complete source-of-truth list and schemas.

PVE credentials are accepted only on create or update payloads and are never returned by API responses. Responses expose only credentialConfigured.

KubeVirt virtualization currently requires a direct Kubernetes client. Agent-connected KubeVirt is explicitly unsupported, and clients must use live capabilities and VM allowedActions instead of assuming PVE parity.

Compute APIs

  • GET /api/v1/compute/capabilities
  • GET /api/v1/compute/overview
  • GET /api/v1/compute/access-sources
  • GET /api/v1/compute/providers
  • GET /api/v1/compute/provider-instances
  • GET /api/v1/compute/provider-instances/:domain/:providerKey/:instanceRef
  • POST /api/v1/compute/provider-instances/:domain/:providerKey/:instanceRef/health-checks
  • POST /api/v1/compute/provider-instances/:domain/:providerKey/:instanceRef/discoveries
  • GET /api/v1/compute/resources/:domain/:kind/:id
  • GET /api/v1/compute/resources/:domain/:kind/:id/relations
  • POST /api/v1/compute/resources/:domain/:kind/:id/actions/:action
  • GET /api/v1/compute/tasks
  • GET /api/v1/compute/tasks/:domain/:id
  • GET /api/v1/compute/tasks/:domain/:id/logs
  • POST /api/v1/compute/tasks/:domain/:id/cancel
  • POST /api/v1/compute/tasks/:domain/:id/retry

These routes are live Core facades over the enabled virtualization and container-runtime providers. Availability still depends on module state, provider capabilities, and the caller’s permissions.

Application APIs

  • GET /api/v1/applications?search=<optional>&limit=100
  • POST /api/v1/applications
  • GET /api/v1/applications/:applicationID
  • GET /api/v1/applications/:applicationID/detail
  • GET /api/v1/applications/:applicationID/runtime
  • GET /api/v1/applications/:applicationID/services
  • POST /api/v1/applications/:applicationID/services
  • GET /api/v1/applications/:applicationID/services/:serviceID
  • PUT /api/v1/applications/:applicationID/services/:serviceID
  • DELETE /api/v1/applications/:applicationID/services/:serviceID
  • POST /api/v1/applications/:applicationID/delivery-actions
  • PUT /api/v1/applications/:applicationID
  • DELETE /api/v1/applications/:applicationID
  • GET /api/v1/build-templates
  • POST /api/v1/build-templates
  • PUT /api/v1/build-templates/:buildTemplateID
  • DELETE /api/v1/build-templates/:buildTemplateID
  • GET /api/v1/delivery/environments
  • GET /api/v1/application-environments
  • POST /api/v1/application-environments
  • GET /api/v1/application-environments/:applicationEnvironmentID
  • PUT /api/v1/application-environments/:applicationEnvironmentID
  • DELETE /api/v1/application-environments/:applicationEnvironmentID
  • GET /api/v1/application-environments/:applicationEnvironmentID/detail
  • GET /api/v1/application-environments/target-candidates?clusterId=<required>&namespace=<required>&search=<optional>
  • GET /api/v1/workflow-templates
  • POST /api/v1/workflow-templates
  • PUT /api/v1/workflow-templates/:workflowTemplateID
  • DELETE /api/v1/workflow-templates/:workflowTemplateID
  • POST /api/v1/delivery/plans
  • GET /api/v1/delivery/plans/:planID
  • POST /api/v1/delivery/plans/:planID/confirm
  • GET /api/v1/delivery/release-board
  • GET /api/v1/delivery/release-bundles?applicationId=<optional>&applicationEnvironmentId=<optional>&limit=50
  • GET /api/v1/delivery/release-bundles/:bundleID
  • GET /api/v1/delivery/release-bundles/:bundleID/artifacts
  • GET /api/v1/delivery/execution-tasks?applicationId=<optional>&applicationEnvironmentId=<optional>&releaseBundleId=<optional>&status=<optional>&providerKind=<optional>&limit=50
  • GET /api/v1/delivery/execution-tasks/:taskID
  • GET /api/v1/delivery/execution-tasks/:taskID/artifacts
  • GET /api/v1/delivery/artifacts
  • POST /api/v1/delivery/execution-tasks/:taskID/cancel
  • POST /api/v1/delivery/execution-tasks/:taskID/retry
  • POST /api/v1/delivery/execution-callbacks
  • GET /api/v1/delivery/execution-tasks/:taskID/runner-status
  • GET /api/v1/builds?applicationId=<optional>&limit=50
  • POST /api/v1/builds/trigger
  • GET /api/v1/workflows?applicationId=<optional>&limit=50
  • POST /api/v1/workflows/trigger
  • POST /api/v1/workflows/:workflowRunID/approve
  • POST /api/v1/workflows/:workflowRunID/reject
  • GET /api/v1/releases?applicationId=<optional>&clusterId=<optional>&limit=50
  • POST /api/v1/releases/trigger
  • GET /api/v1/integrations/gitlab/projects?search=<optional>&limit=50
  • GET /api/v1/integrations/gitlab/branches?projectId=<required>&search=<optional>&limit=50
  • GET /api/v1/integrations/gitlab/tags?projectId=<required>&search=<optional>&limit=50

The console creates and confirms DeliveryPlan as its canonical delivery write path. Direct build, workflow, and release trigger endpoints remain compatibility APIs.

Copilot APIs

  • GET /api/v1/copilot/insights
  • GET /api/v1/copilot/sessions
  • GET /api/v1/copilot/sessions/:sessionID
  • POST /api/v1/copilot/sessions
  • PATCH /api/v1/copilot/sessions/:sessionID
  • DELETE /api/v1/copilot/sessions/:sessionID
  • GET /api/v1/copilot/sessions/:sessionID/messages
  • POST /api/v1/copilot/sessions/:sessionID/messages
  • POST /api/v1/copilot/sessions/:sessionID/messages/stream
  • POST /api/v1/copilot/global-assistant/events
  • POST /api/v1/copilot/sessions/:sessionID/analyze
  • GET /api/v1/copilot/root-cause/runs
  • POST /api/v1/copilot/root-cause/runs
  • GET /api/v1/copilot/root-cause/runs/:runID
  • GET /api/v1/copilot/agent-providers
  • GET /api/v1/copilot/agent-runs
  • GET /api/v1/copilot/data-source-capabilities
  • GET /api/v1/copilot/data-sources
  • POST /api/v1/copilot/data-sources
  • PUT /api/v1/copilot/data-sources/:dataSourceID
  • POST /api/v1/copilot/data-sources/:dataSourceID/validate
  • GET /api/v1/copilot/analysis-profiles
  • POST /api/v1/copilot/analysis-profiles
  • PUT /api/v1/copilot/analysis-profiles/:profileID
  • GET /api/v1/copilot/automation-policies
  • POST /api/v1/copilot/automation-policies
  • PUT /api/v1/copilot/automation-policies/:policyID
  • GET /api/v1/copilot/inspection-tasks
  • POST /api/v1/copilot/inspection-tasks
  • PUT /api/v1/copilot/inspection-tasks/:taskID
  • GET /api/v1/copilot/inspection-runs
  • POST /api/v1/copilot/inspection-tasks/:taskID/execute
  • POST /api/v1/copilot/agent-runs/claim
  • POST /api/v1/copilot/agent-runs/callback
  • POST /api/v1/copilot/agent-runs/tool-call

/copilot/agent-runs/claim, /copilot/agent-runs/callback, and /copilot/agent-runs/tool-call are runner-facing APIs and require Authorization: Bearer <runtime.execution_runner_token>. Tool calls also require the per-run callbackToken; the control plane only executes tools present in the AgentRun.toolBindings snapshot and records the result as ToolExecution.

POST /copilot/root-cause/runs accepts agentProviderId, analysisProfileId, and triggerType. agentProviderId=internal runs the built-in analyzer synchronously; external providers such as hermes create a queued root-cause business run plus a linked AgentRun, then backfill the business run from the runner callback.

AI Platform APIs

  • GET /api/v1/ai/agent-providers/catalog
  • GET /api/v1/ai/agent-providers/runtime-status
  • GET /api/v1/ai/agent-providers/registry-snapshot
  • POST /api/v1/ai/agent-providers/registry-acks
  • GET /api/v1/ai/agent-providers/rollouts
  • POST /api/v1/ai/agent-providers/rollouts
  • POST /api/v1/ai/agent-providers/rollouts/:rolloutID/:rolloutAction
  • GET /api/v1/ai/agent-providers/conformance-runs
  • POST /api/v1/ai/agent-providers/conformance-runs
  • GET /api/v1/ai/agent-runs/multi-agent
  • POST /api/v1/ai/agent-runs/multi-agent
  • POST /api/v1/ai/agent-runs/multi-agent/:planID/subtasks/:subtaskID/complete
  • POST /api/v1/ai/agent-runs/multi-agent/:planID/cancel
  • GET /api/v1/ai/knowledge-bases
  • POST /api/v1/ai/knowledge-bases
  • GET /api/v1/ai/knowledge-bases/:baseID
  • PATCH /api/v1/ai/knowledge-bases/:baseID
  • DELETE /api/v1/ai/knowledge-bases/:baseID
  • GET /api/v1/ai/knowledge-bases/:baseID/sources
  • POST /api/v1/ai/knowledge-bases/:baseID/sources
  • POST /api/v1/ai/knowledge-bases/:baseID/sources/:sourceID/sync
  • GET /api/v1/ai/knowledge-bases/:baseID/documents
  • GET /api/v1/ai/knowledge-bases/:baseID/sync-runs
  • GET /api/v1/ai/knowledge-bases/:baseID/index-revisions
  • GET /api/v1/ai/knowledge-bases/:baseID/graph-revisions
  • POST /api/v1/ai/knowledge-bases/:baseID/graph-revisions
  • POST /api/v1/ai/knowledge-bases/:baseID/graph-revisions/:revisionID/publish
  • POST /api/v1/ai/knowledge-bases/:baseID/graph-revisions/:revisionID/query
  • POST /api/v1/ai/knowledge-bases/:baseID/rebuild
  • POST /api/v1/ai/knowledge/search
  • POST /api/v1/ai/context/inspect
  • GET /api/v1/ai/knowledge/connectors
  • POST /api/v1/ai/knowledge/connectors
  • POST /api/v1/ai/knowledge/connectors/:connectorID/validate
  • POST /api/v1/ai/knowledge-bases/:baseID/sync-jobs
  • GET /api/v1/ai/knowledge/sync-jobs/:jobID
  • POST /api/v1/ai/knowledge/sync-jobs/:jobID/cancel
  • POST /api/v1/ai/knowledge/sync-jobs/:jobID/retry
  • GET /api/v1/ai/evaluations/datasets
  • POST /api/v1/ai/evaluations/datasets
  • GET /api/v1/ai/evaluations/runs
  • POST /api/v1/ai/evaluations/runs
  • GET /api/v1/ai/evaluations/runs/:runID
  • GET /api/v1/ai/evaluations/runs/:runID/results
  • POST /api/v1/ai/evaluations/runs/:runID/complete
  • GET /api/v1/ai/evaluations/executor-profiles
  • POST /api/v1/ai/evaluations/executor-profiles
  • POST /api/v1/ai/evaluations/runs/:runID/execute
  • GET /api/v1/ai/evaluations/runs/:runID/attempts
  • GET /api/v1/ai/evaluations/replays
  • POST /api/v1/ai/evaluations/replays
  • GET /api/v1/ai/evaluations/gate-policies
  • POST /api/v1/ai/evaluations/gate-policies
  • GET /api/v1/ai/evaluations/gate-decisions
  • POST /api/v1/ai/evaluations/gates/evaluate
  • GET /api/v1/ai/evaluations/feedback
  • POST /api/v1/ai/evaluations/feedback
  • GET /api/v1/ai/memory/policies
  • POST /api/v1/ai/memory/policies
  • GET /api/v1/ai/memory
  • POST /api/v1/ai/memory
  • DELETE /api/v1/ai/memory/:memoryID
  • GET /api/v1/ai/environments/templates
  • POST /api/v1/ai/environments/templates
  • GET /api/v1/ai/environments/leases
  • POST /api/v1/ai/environments/leases/:leaseID/release
  • POST /api/v1/ai/environments/gc
  • GET /api/v1/ai/operations
  • POST /api/v1/ai/operations
  • GET /api/v1/ai/operations/runbook-evidence

AI Gateway APIs

The public OpenAPI contract in ../soha/contracts/openapi/soha-api.yaml currently covers the Gateway, token, audit, approval, governance, and MCP capability boundaries below:

  • GET /api/v1/ai-gateway/capabilities
  • POST /api/v1/ai-gateway/plans/validate
  • POST /api/v1/ai-gateway/tasks
  • GET /api/v1/ai-gateway/tasks
  • GET /api/v1/ai-gateway/tasks/:taskId
  • POST /api/v1/ai-gateway/tasks/:taskId/resume
  • POST /api/v1/ai-gateway/tasks/:taskId/cancel
  • POST /api/v1/ai-gateway/tools/:toolName/invoke
  • POST /api/v1/ai-gateway/resources/read
  • POST /api/v1/ai-gateway/prompts/get
  • GET /api/v1/ai-gateway/personal-access-tokens
  • POST /api/v1/ai-gateway/personal-access-tokens
  • POST /api/v1/ai-gateway/personal-access-tokens/:tokenID/revoke
  • POST /api/v1/ai-gateway/personal-access-tokens/:tokenID/rotate
  • GET /api/v1/ai-gateway/service-accounts
  • POST /api/v1/ai-gateway/service-accounts
  • GET /api/v1/ai-gateway/service-account-tokens
  • POST /api/v1/ai-gateway/service-accounts/:serviceAccountID/tokens
  • POST /api/v1/ai-gateway/service-account-tokens/:tokenID/revoke
  • POST /api/v1/ai-gateway/service-account-tokens/:tokenID/rotate
  • POST /api/v1/ai-gateway/governed-credentials/personal-access-tokens
  • POST /api/v1/ai-gateway/governed-credentials/personal-access-tokens/:tokenID/rotate
  • POST /api/v1/ai-gateway/governed-credentials/service-accounts/:serviceAccountID/tokens
  • POST /api/v1/ai-gateway/governed-credentials/service-account-tokens/:tokenID/rotate
  • GET /api/v1/ai-gateway/audit-logs
  • GET /api/v1/ai-gateway/approval-requests
  • GET /api/v1/ai-gateway/approval-requests/:requestID/timeline
  • POST /api/v1/ai-gateway/approval-requests/:requestID/:action
  • POST /api/v1/ai-gateway/approval-requests/:requestID/approve
  • POST /api/v1/ai-gateway/approval-requests/:requestID/reject
  • POST /api/v1/ai-gateway/approval-requests/:requestID/cancel
  • GET /api/v1/ai-gateway/governance/status
  • GET /api/v1/ai-gateway/relay/upstreams
  • POST /api/v1/ai-gateway/relay/upstreams
  • PUT /api/v1/ai-gateway/relay/upstreams/:upstreamID
  • POST /api/v1/ai-gateway/relay/upstreams/test
  • POST /api/v1/ai-gateway/relay/upstreams/health-checks/run
  • POST /api/v1/ai-gateway/relay/upstreams/:upstreamID/test
  • GET /api/v1/ai-gateway/relay/model-routes
  • POST /api/v1/ai-gateway/relay/model-routes
  • PUT /api/v1/ai-gateway/relay/model-routes/:routeID
  • DELETE /api/v1/ai-gateway/relay/model-routes/:routeID
  • GET /api/v1/ai-gateway/relay/model-calls
  • GET /api/v1/ai-gateway/relay/metrics
  • GET /api/v1/ai-gateway/llm/openai/v1/models
  • POST /api/v1/ai-gateway/llm/openai/v1/chat/completions
  • POST /api/v1/ai-gateway/llm/openai/v1/responses
  • POST /api/v1/ai-gateway/llm/openai/v1/embeddings
  • POST /api/v1/ai-gateway/llm/openai/v1/images/generations
  • POST /api/v1/ai-gateway/llm/openai/v1/images/edits
  • POST /api/v1/ai-gateway/llm/openai/v1/images/variations
  • POST /api/v1/ai-gateway/llm/openai/v1/audio/speech
  • POST /api/v1/ai-gateway/llm/openai/v1/audio/transcriptions
  • POST /api/v1/ai-gateway/llm/openai/v1/audio/translations
  • GET /api/v1/ai-gateway/llm/openai/v1/realtime
  • GET /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/models
  • POST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/chat/completions
  • POST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/responses
  • POST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/embeddings
  • POST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/images/generations
  • POST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/images/edits
  • POST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/images/variations
  • POST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/audio/speech
  • POST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/audio/transcriptions
  • POST /api/v1/ai-gateway/llm/:openaiCompatibleProvider/v1/audio/translations
  • GET /api/v1/ai-gateway/llm/gemini/v1beta/models
  • POST /api/v1/ai-gateway/llm/gemini/v1beta/models
  • POST /api/v1/ai-gateway/llm/gemini/v1beta/models/:geminiModel:generateContent
  • POST /api/v1/ai-gateway/llm/gemini/v1beta/models/:geminiModel:streamGenerateContent
  • POST /api/v1/ai-gateway/llm/gemini/v1beta/interactions
  • POST /api/v1/ai-gateway/llm/cohere/v2/rerank
  • GET /api/v1/ai-gateway/llm/anthropic/v1/models
  • POST /api/v1/ai-gateway/llm/anthropic/v1/messages
  • GET /api/v1/mcp/capabilities

Marketplace APIs

  • GET /api/v1/marketplace/index.json
  • GET /api/v1/marketplace/plugins/:pluginID/:version/plugin.manifest.json

Planned relay contracts in the same OpenAPI artifact, not routed by the backend yet:

  • GET /api/v1/ai-gateway/relay/cache/stats
  • POST /api/v1/ai-gateway/relay/cache/purge

/ai-gateway/capabilities returns the current caller’s AI-native tools, resources, prompts, and skills after backend permission filtering. AI clients should send X-Soha-AI-Client-ID, X-Soha-AI-Client, and X-Soha-Skill-ID when available so audit records can distinguish human, service, client, skill, and tool context.

/ai-gateway/plans/validate validates a capability plan before execution; /ai-gateway/tasks creates and lists durable tasks, with permissions and current conditions checked again for each step. Resuming creates a plan revision; cancellation preserves side effects of steps already completed.

/ai-gateway/tools/:toolName/invoke is the shared MCP/CLI/AI-agent tool invocation entry point. It must re-check Gateway permission, domain permission, scope, grants, and risk policy, then call the owning application service instead of bypassing soha control-plane logic.

/ai-gateway/resources/read and /ai-gateway/prompts/get are the backend-only MCP resource and prompt boundaries. The local soha mcp process only proxies these calls; it does not build privileged resource documents or prompt content locally.

/ai-gateway/governance/status is the read-only Gateway operations endpoint. It summarizes recent audit data, pending approvals, token/client findings, policy coverage, high-risk guardrail findings, redaction coverage, and resource-scope coverage.

/ai-gateway/approval-requests/:requestID/:action accepts approve, reject, and cancel. The concrete action URLs are documented above for CLI and operator runbook use. Approval replay still happens inside the Gateway application service after it re-checks the original grant, access policy, skill binding, current permissions, and business service authorization.

/ai-gateway/relay/* manages model relay upstreams, model routes, model-call logs, and metrics. Response cache stats and purge contracts are planned for the response-cache phase. Management responses use the OpenSoha response envelope and require relay view or manage permissions.

/ai-gateway/llm/* exposes OpenAI-, Anthropic-, Gemini-, Cohere-, and OpenAI-compatible provider APIs for SDKs. These endpoints cover model discovery, chat/responses, embeddings, image and audio operations, realtime access, and reranking where the provider supports them. They accept existing soha_pat_ and soha_sat_ credentials through bearer auth or x-api-key, require explicit relay token metadata, and return native provider-shaped JSON or streaming responses without an OpenSoha envelope.

Public OpenAPI contract status:

  • Contracted Gateway runtime, token, audit, approval, governance, and MCP capability endpoints are listed above and are checked against ../soha/contracts/openapi/soha-api.yaml.

  • Pending contracts addition: the console management endpoints below are implemented by the core/web Gateway workbench, but are not yet included in the public OpenAPI artifact.

  • GET /api/v1/ai-gateway/ai-clients

  • POST /api/v1/ai-gateway/ai-clients

  • PUT /api/v1/ai-gateway/ai-clients/:clientID

  • GET /api/v1/ai-gateway/tool-grants

  • POST /api/v1/ai-gateway/tool-grants

  • DELETE /api/v1/ai-gateway/tool-grants/:grantID

  • GET /api/v1/ai-gateway/access-policies

  • POST /api/v1/ai-gateway/access-policies

  • PUT /api/v1/ai-gateway/access-policies/:policyID

  • DELETE /api/v1/ai-gateway/access-policies/:policyID

  • GET /api/v1/ai-gateway/skill-bindings

  • POST /api/v1/ai-gateway/skill-bindings

  • PUT /api/v1/ai-gateway/skill-bindings/:bindingID

  • DELETE /api/v1/ai-gateway/skill-bindings/:bindingID

Current Gateway tool names:

  • delivery.applications.list
  • delivery.applications.detail
  • delivery.applications.create
  • delivery.application_environments.list
  • delivery.application_services.list
  • delivery.build_sources.list
  • delivery.release_targets.list
  • delivery.actions.trigger
  • delivery.release_bundles.list
  • delivery.execution_tasks.list
  • delivery.execution_logs.list
  • delivery.workflow_templates.list
  • delivery.release_context.diff
  • delivery.rollback.context
  • k8s.pods.list
  • k8s.pods.logs
  • k8s.pods.describe
  • k8s.deployments.list
  • k8s.deployments.rollout_status
  • k8s.deployments.events
  • k8s.services.list
  • k8s.services.backends
  • k8s.routes.context
  • k8s.storage.context
  • k8s.nodes.detail
  • k8s.events.list
  • diagnosis.release_failure.analyze

Kubernetes tools are read-only and are routed through the platform resource application service. Gateway applies basic sensitive-field redaction to log outputs before returning them to MCP/CLI callers.

Personal and service-account token create and rotate responses return the opaque token value once. The database stores only the hash and prefix; callers must keep the returned value in their local CLI/MCP credential store.

AI client, tool-grant, access-policy, and skill-binding endpoints require ai.gateway.manage. Tool grants, access policies, and skill bindings support user, service_account, role, and ai_client subjects; runtime evaluation combines subject, role, and client records. Deny policies and grants take precedence, allow records form allow-lists, and skill bindings narrow the exposed skill/capability refs without granting new permissions.

Tool invocations write both the standard audit log and ai_gateway_audit_logs. The dedicated AI Gateway row records actor, AI client, skill, tool, risk level, resource scope, request/result, and related IDs without storing full tokens, kubeconfigs, raw logs, or complete tool input.

Application Payload

{ "id": "billing-api", "name": "Billing API", "key": "billing-api", "group": "commerce", "language": "Go", "description": "Core billing service", "ownerTeam": "platform", "repositoryProvider": "gitlab", "repositoryProjectId": "12345", "repositoryPath": "platform/billing-api", "defaultBranch": "main", "defaultTag": "v1.0.0", "buildImage": "registry.example.com/platform/billing-api", "buildContextDir": ".", "dockerfilePath": "Dockerfile", "buildSources": [ { "id": "default:billing-api", "name": "Repository Dockerfile", "type": "repo_dockerfile", "enabled": true, "isDefault": true, "buildImage": "registry.example.com/platform/billing-api", "defaultTag": "v1.0.0", "config": { "contextDir": ".", "dockerfilePath": "Dockerfile", "builderKind": "docker" } } ], "enabled": true, "metadata": { "tier": "core" } }

Build Trigger Payload

{ "applicationId": "billing-api", "applicationEnvironmentId": "binding-prod", "buildSourceId": "default:billing-api", "refType": "branch", "refName": "main", "imageTag": "billing-api:manual-20260322", "buildArgs": { "profile": "default" }, "variables": { "GO_VERSION": "1.24" } }

Execution Callback Payload

{ "callbackToken": "task-callback-token", "status": "completed", "payload": { "logs": [ "checkout source", "build image completed" ], "image": "registry.example.com/platform/billing-api:20260505", "imageDigest": "sha256:..." } }

Alert Webhook Payload

{ "source": "alertmanager", "alerts": [ { "fingerprint": "cpu-high-prod-1", "title": "CPUHigh", "summary": "CPU usage exceeded threshold", "severity": "critical", "status": "firing", "clusterId": "local", "namespace": "default", "labels": { "alertname": "CPUHigh", "team": "platform" }, "annotations": { "runbook": "https://example.internal/runbooks/cpu-high" }, "receiver": "platform-default", "generatorUrl": "http://prometheus.local/graph" } ] }

Headers:

  • X-Soha-Webhook-Token: <monitoring.webhook_token> or
  • Authorization: Bearer <monitoring.webhook_token>

Notification Channel Payload

{ "id": "platform-default-webhook", "name": "Platform Default Webhook", "channelType": "webhook", "enabled": true, "config": { "url": "https://notify.example.internal/hooks/platform-alerts", "method": "POST" } }

Cluster Registration Payload

Direct kubeconfig

{ "id": "direct-prod-01", "name": "Direct Production 01", "region": "cn-shanghai", "environment": "production", "labels": { "provider": "kubeconfig", "owner": "platform" }, "connectionMode": "direct_kubeconfig", "kubeconfig": "apiVersion: v1\n..." }

Agent

{ "id": "edge-prod-01", "name": "Edge Production 01", "region": "cn-shanghai", "environment": "production", "labels": { "provider": "agent", "owner": "platform" }, "connectionMode": "agent", "agentEndpoint": "https://agent.example.internal", "agentToken": "optional-bearer-token" }
Last updated on