ClawSpan

ClawSpan System API

Health and operational endpoints

GitHub OpenAPI

Operations 33

GET /api/v1/health Gateway health and runtime mode #
GET /api/v1/readiness Readiness probes (backend/auth/redis/payment checks) #
GET /api/v1/auth/bootstrap Authentication bootstrap and JWKS/OIDC readiness metadata #
GET /api/v1/metrics In-process gateway metrics snapshot #
GET /api/v1/metrics/prometheus Prometheus metrics scrape endpoint #
GET /api/v1/control/plane Control-plane autoscaling/backpressure/fail-safe recommendation snapshot #
GET /api/v1/control/plane/history Control-plane snapshot history for reliability-policy agents #
GET /api/v1/control/plane/actions List privileged control-plane action audit log and current execution state #
POST /api/v1/control/plane/actions Execute one privileged control-plane action with deterministic idempotency #
POST /api/v1/control/plane/reconcile Execute control-plane remediation queue in one privileged operation #
GET /api/v1/capabilities Machine-readable runtime capabilities #
GET /api/v1/capabilities/graph Canonical versioned capability graph for agent discoverability #
GET /api/v1/capabilities/graph/{version} Fetch one capability graph version #
GET /api/v1/contracts/dual-plane Dual-plane authority and bridge contract for machine discoverability #
GET /api/v1/contracts/dual-plane/errors Deterministic error catalog aggregated from capability execution contracts #
GET /api/v1/openapi OpenAPI description of this gateway #
POST /api/v1/maintenance/payload-ttl/prune Prune/redact expired payloads based on TTL policy (admin/system) #
GET /api/health Deprecated alias of /api/v1/health #
GET /api/readiness Deprecated alias of /api/v1/readiness #
GET /api/auth/bootstrap Deprecated alias of /api/v1/auth/bootstrap #
GET /api/metrics Deprecated alias of /api/v1/metrics #
GET /api/control/plane Deprecated alias of /api/v1/control/plane #
GET /api/control/plane/history Deprecated alias of /api/v1/control/plane/history #
GET /api/control/plane/actions Deprecated alias of /api/v1/control/plane/actions #
POST /api/control/plane/actions Deprecated alias of /api/v1/control/plane/actions #
POST /api/control/plane/reconcile Deprecated alias of /api/v1/control/plane/reconcile #
GET /api/capabilities Deprecated alias of /api/v1/capabilities #
GET /api/capabilities/graph Deprecated alias of /api/v1/capabilities/graph #
GET /api/capabilities/graph/{version} Deprecated alias of /api/v1/capabilities/graph/{version} #
GET /api/contracts/dual-plane Deprecated alias of /api/v1/contracts/dual-plane #
GET /api/contracts/dual-plane/errors Deprecated alias of /api/v1/contracts/dual-plane/errors #
GET /api/openapi Deprecated alias of /api/v1/openapi #
POST /api/maintenance/payload-ttl/prune Deprecated alias of /api/v1/maintenance/payload-ttl/prune #

Documentation

📖
Documentation
https://clawspan.cloud/technical/
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/clawspan-cloud/refs/heads/main/authentication/clawspan-cloud-authentication.yml
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/clawspan-cloud/refs/heads/main/rate-limits/clawspan-cloud-rate-limits.yml
📖
Documentation
https://clawspan.cloud/signalhub/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/clawspan-cloud/refs/heads/main/openapi/clawspan-cloud-system-api-openapi.yml

Other Resources

🔗
LLMsTxt
https://app.clawspan.cloud/llms.txt
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/clawspan-cloud/refs/heads/main/errors/clawspan-cloud-problem-types.yml
🔗
ErrorCatalog
https://app.clawspan.cloud/v1/contracts/dual-plane/errors
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/clawspan-cloud/refs/heads/main/conventions/clawspan-cloud-conventions.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/clawspan-cloud/refs/heads/main/data-model/clawspan-cloud-data-model.yml
🔗
AgenticAccess
https://raw.githubusercontent.com/api-evangelist/clawspan-cloud/refs/heads/main/agentic-access/clawspan-cloud-agentic-access.yml
🔗
Sandbox
https://raw.githubusercontent.com/api-evangelist/clawspan-cloud/refs/heads/main/sandbox/clawspan-cloud-sandbox.yml
🔗
AgentCard
https://raw.githubusercontent.com/api-evangelist/clawspan-cloud/refs/heads/main/a2a/clawspan-cloud-signalhub-a2a.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/clawspan-cloud:clawspan-cloud-system-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

clawspan-cloud-system-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: SignalHub Gateway System API
  version: 1.0.0-beta
  description: Agent-first signal exchange gateway API. Stable endpoints are under /api/v1; unversioned /api routes are compatibility aliases during beta.
servers:
- url: https://signalhub.clawspan.dev
tags:
- name: System
  description: Health and operational endpoints
paths:
  /api/v1/health:
    get:
      tags:
      - System
      summary: Gateway health and runtime mode
      operationId: getApiV1Health
      x-operation-id-source: derived
  /api/v1/readiness:
    get:
      tags:
      - System
      summary: Readiness probes (backend/auth/redis/payment checks)
      parameters:
      - name: x-metrics-token
        in: header
        required: false
        schema:
          type: string
      operationId: getApiV1Readiness
      x-operation-id-source: derived
  /api/v1/auth/bootstrap:
    get:
      tags:
      - System
      summary: Authentication bootstrap and JWKS/OIDC readiness metadata
      parameters:
      - name: refresh
        in: query
        required: false
        schema:
          type: boolean
      operationId: getApiV1AuthBootstrap
      x-operation-id-source: derived
  /api/v1/metrics:
    get:
      tags:
      - System
      summary: In-process gateway metrics snapshot
      parameters:
      - name: x-metrics-token
        in: header
        required: false
        schema:
          type: string
      operationId: getApiV1Metrics
      x-operation-id-source: derived
  /api/v1/metrics/prometheus:
    get:
      tags:
      - System
      summary: Prometheus metrics scrape endpoint
      parameters:
      - name: x-metrics-token
        in: header
        required: false
        schema:
          type: string
      operationId: getApiV1MetricsPrometheus
      x-operation-id-source: derived
  /api/v1/control/plane:
    get:
      tags:
      - System
      summary: Control-plane autoscaling/backpressure/fail-safe recommendation snapshot
      parameters:
      - name: x-metrics-token
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Deterministic control-plane signal snapshot for reliability automation
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  controlPlane:
                    type: object
                    properties:
                      signals:
                        type: object
                        properties:
                          scalePressureScore:
                            type: number
                          queuePressure:
                            type: number
                          realtimeFallbackRate:
                            type: number
                          realtimeDirectContractMissRate:
                            type: number
                          realtimeProjectionRefreshCount:
                            type: number
                          realtimeProjectionRefreshRate:
                            type: number
                          realtimeSuccessRate:
                            type: number
                          bridgeLagSeconds:
                            type: number
                          marginRiskScore:
                            type: number
                          trendWindowSize:
                            type: number
                          trendAccelerationScore:
                            type: number
                          scalePressureDelta:
                            type: number
                          queuePressureDelta:
                            type: number
                          marginRiskDelta:
                            type: number
                          realtimeFallbackRateDelta:
                            type: number
                          realtimeDirectContractMissRateDelta:
                            type: number
                          realtimeProjectionRefreshRateDelta:
                            type: number
                          bridgeFailureRateDelta:
                            type: number
                          errorRateDelta:
                            type: number
                      autoscaling:
                        type: object
                        properties:
                          recommendation:
                            type: string
                          desiredReplicaMultiplier:
                            type: number
                      backpressure:
                        type: object
                        properties:
                          mode:
                            type: string
                          dropNonCriticalStreams:
                            type: boolean
                          deferPricingSweep:
                            type: boolean
                          throttleWriteRoutes:
                            type: boolean
                      failsafe:
                        type: object
                        properties:
                          realtimeDegraded:
                            type: boolean
                          pricingFrozenRecommended:
                            type: boolean
                          settlementPauseRecommended:
                            type: boolean
                          abuseStrictRecommended:
                            type: boolean
                      actionQueue:
                        type: array
                        items:
                          type: object
                          properties:
                            action:
                              type: string
                            severity:
                              type: string
                            reasonCode:
                              type: string
                      marginProtection:
                        type: object
                        properties:
                          health:
                            type: string
                          pricingGuardrailEvents:
                            type: number
                          negativeMarginEvents:
                            type: number
                          marginRiskScore:
                            type: number
                          affiliateFraudTransitions:
                            type: number
                          reactionAbuseBlocks:
                            type: number
      operationId: getApiV1ControlPlane
      x-operation-id-source: derived
  /api/v1/control/plane/history:
    get:
      tags:
      - System
      summary: Control-plane snapshot history for reliability-policy agents
      parameters:
      - name: x-metrics-token
        in: header
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: refresh
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Deterministic control-plane history envelope
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  history:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      entries:
                        type: array
                        items:
                          type: object
                          properties:
                            recordedAt:
                              type: string
                            source:
                              type: string
                            snapshot:
                              type: object
      operationId: getApiV1ControlPlaneHistory
      x-operation-id-source: derived
  /api/v1/control/plane/actions:
    get:
      tags:
      - System
      summary: List privileged control-plane action audit log and current execution state
      security:
      - bearerAuth: []
      - agentHeader: []
      parameters:
      - name: x-metrics-token
        in: header
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
      responses:
        '200':
          description: Control-plane action audit and execution-state snapshot
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  allowedActions:
                    type: array
                    items:
                      type: string
                  state:
                    type: object
                    properties:
                      schemaVersion:
                        type: string
                      gatewayReplicaMultiplier:
                        type: integer
                      nonCriticalStreamsThrottled:
                        type: boolean
                      realtimeDegradedModeEnabled:
                        type: boolean
                      pricingFrozenModeEnabled:
                        type: boolean
                      affiliatePayoutsFrozen:
                        type: boolean
                      affiliateHoldbacksTightened:
                        type: boolean
                      settlementBridgePaused:
                        type: boolean
                      abuseStrictModeEnabled:
                        type: boolean
                      updatedAt:
                        type: string
                        nullable: true
                  cooldowns:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        action:
                          type: string
                        inCooldown:
                          type: boolean
                        retryAfterSeconds:
                          type: integer
                        cooldownSeconds:
                          type: integer
                        lastRecordedAt:
                          type: string
                          nullable: true
                  audit:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      entries:
                        type: array
                        items:
                          type: object
                          properties:
                            executionId:
                              type: string
                            actorId:
                              type: string
                            action:
                              type: string
                            reasonCode:
                              type: string
                            source:
                              type: string
                            dryRun:
                              type: boolean
                            outcome:
                              type: string
                            applied:
                              type: boolean
                            recordedAt:
                              type: string
      operationId: getApiV1ControlPlaneActions
      x-operation-id-source: derived
    post:
      tags:
      - System
      summary: Execute one privileged control-plane action with deterministic idempotency
      security:
      - bearerAuth: []
      - agentHeader: []
      parameters:
      - name: x-metrics-token
        in: header
        required: false
        schema:
          type: string
      - name: x-control-plane-apply-token
        in: header
        required: false
        schema:
          type: string
        description: Required for non-dry-run action execution in non-development environments when control-plane apply mode is enabled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                reasonCode:
                  type: string
                source:
                  type: string
                dryRun:
                  type: boolean
                idempotencyKey:
                  type: string
      responses:
        '200':
          description: Control-plane action execution envelope
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  execution:
                    type: object
                    properties:
                      executionId:
                        type: string
                      action:
                        type: string
                      outcome:
                        type: string
                      applied:
                        type: boolean
                      idempotencyReplayed:
                        type: boolean
                      recordedAt:
                        type: string
                  state:
                    type: object
                    properties:
                      schemaVersion:
                        type: string
                      gatewayReplicaMultiplier:
                        type: integer
                      nonCriticalStreamsThrottled:
                        type: boolean
                      realtimeDegradedModeEnabled:
                        type: boolean
                      pricingFrozenModeEnabled:
                        type: boolean
                      affiliatePayoutsFrozen:
                        type: boolean
                      affiliateHoldbacksTightened:
                        type: boolean
                      settlementBridgePaused:
                        type: boolean
                      abuseStrictModeEnabled:
                        type: boolean
                      updatedAt:
                        type: string
                        nullable: true
        '400':
          description: Invalid control-plane action request payload
        '401':
          description: Missing or invalid authentication context
        '403':
          description: Missing metrics token, insufficient role claims, apply mode disabled, or missing/invalid control-plane apply token
        '409':
          description: Idempotency conflict for control-plane action replay
        '429':
          description: Action rejected by control-plane cooldown guardrail
      operationId: postApiV1ControlPlaneActions
      x-operation-id-source: derived
  /api/v1/control/plane/reconcile:
    post:
      tags:
      - System
      summary: Execute control-plane remediation queue in one privileged operation
      security:
      - bearerAuth: []
      - agentHeader: []
      parameters:
      - name: x-metrics-token
        in: header
        required: false
        schema:
          type: string
      - name: x-control-plane-apply-token
        in: header
        required: false
        schema:
          type: string
        description: Required for mode=apply in non-development environments when control-plane apply mode is enabled.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  type: string
                  enum:
                  - balanced
                  - safety_first
                  - throughput_first
                mode:
                  type: string
                  enum:
                  - dry-run
                  - apply
                source:
                  type: string
                strictFailures:
                  type: boolean
                maxActions:
                  type: integer
                  minimum: 1
                  maximum: 100
                minSeverity:
                  type: string
                  enum:
                  - low
                  - medium
                  - high
                allowedActions:
                  type: array
                  items:
                    type: string
                idempotencyKeyPrefix:
                  type: string
      responses:
        '200':
          description: Control-plane reconciliation plan/execution envelope
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  reconciliation:
                    type: object
                    properties:
                      profile:
                        type: string
                        enum:
                        - balanced
                        - safety_first
                        - throughput_first
                      mode:
                        type: string
                      strictFailures:
                        type: boolean
                      source:
                        type: string
                      maxActions:
                        type: integer
                      droppedActions:
                        type: integer
                      snapshotGeneratedAt:
                        type: string
                      snapshot:
                        type: object
                      plan:
                        type: object
                      summary:
                        type: object
                      state:
                        type: object
                      results:
                        type: array
                        items:
                          type: object
        '400':
          description: Invalid control-plane reconcile request payload
        '401':
          description: Missing or invalid authentication context
        '403':
          description: Missing metrics token, insufficient role claims, apply mode disabled, or missing/invalid control-plane apply token
        '409':
          description: Strict reconcile mode reported one or more action failures
      operationId: postApiV1ControlPlaneReconcile
      x-operation-id-source: derived
  /api/v1/capabilities:
    get:
      tags:
      - System
      summary: Machine-readable runtime capabilities
      operationId: getApiV1Capabilities
      x-operation-id-source: derived
  /api/v1/capabilities/graph:
    get:
      tags:
      - System
      summary: Canonical versioned capability graph for agent discoverability
      parameters:
      - name: version
        in: query
        required: false
        schema:
          type: string
          minLength: 3
          maxLength: 80
      responses:
        '200':
          description: Capability graph envelope with machine-executable node contracts
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  latestVersion:
                    type: string
                  versions:
                    type: array
                    items:
                      type: string
                  graph:
                    type: object
                    properties:
                      graphVersion:
                        type: string
                      nodes:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            method:
                              type: string
                            path:
                              type: string
                            executionContract:
                              type: object
                              properties:
                                retry:
                                  type: object
                                idempotency:
                                  type: object
                                deterministicErrors:
                                  type: array
                                  items:
                                    type: object
                                transport:
                                  type: object
                                request:
                                  type: object
                                response:
                                  type: object
                      edges:
                        type: array
                        items:
                          type: object
                      intentToAction:
                        type: array
                        items:
                          type: object
      operationId: getApiV1CapabilitiesGraph
      x-operation-id-source: derived
  /api/v1/capabilities/graph/{version}:
    get:
      tags:
      - System
      summary: Fetch one capability graph version
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          minLength: 3
          maxLength: 80
      responses:
        '200':
          description: Pinned capability graph version with deterministic execution contracts
        '404':
          description: Capability graph version not found
      operationId: getApiV1CapabilitiesGraphByVersion
      x-operation-id-source: derived
  /api/v1/contracts/dual-plane:
    get:
      tags:
      - System
      summary: Dual-plane authority and bridge contract for machine discoverability
      operationId: getApiV1ContractsDualPlane
      x-operation-id-source: derived
  /api/v1/contracts/dual-plane/errors:
    get:
      tags:
      - System
      summary: Deterministic error catalog aggregated from capability execution contracts
      operationId: getApiV1ContractsDualPlaneErrors
      x-operation-id-source: derived
  /api/v1/openapi:
    get:
      tags:
      - System
      summary: OpenAPI description of this gateway
      operationId: getApiV1Openapi
      x-operation-id-source: derived
  /api/v1/maintenance/payload-ttl/prune:
    post:
      tags:
      - System
      summary: Prune/redact expired payloads based on TTL policy (admin/system)
      security:
      - bearerAuth: []
      - agentHeader: []
      operationId: postApiV1MaintenancePayloadTtlPrune
      x-operation-id-source: derived
  /api/health:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/health
      operationId: getApiHealth
      x-operation-id-source: derived
  /api/readiness:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/readiness
      operationId: getApiReadiness
      x-operation-id-source: derived
  /api/auth/bootstrap:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/auth/bootstrap
      operationId: getApiAuthBootstrap
      x-operation-id-source: derived
  /api/metrics:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/metrics
      operationId: getApiMetrics
      x-operation-id-source: derived
  /api/control/plane:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/control/plane
      operationId: getApiControlPlane
      x-operation-id-source: derived
  /api/control/plane/history:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/control/plane/history
      operationId: getApiControlPlaneHistory
      x-operation-id-source: derived
  /api/control/plane/actions:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/control/plane/actions
      operationId: getApiControlPlaneActions
      x-operation-id-source: derived
    post:
      tags:
      - System
      summary: Deprecated alias of /api/v1/control/plane/actions
      operationId: postApiControlPlaneActions
      x-operation-id-source: derived
  /api/control/plane/reconcile:
    post:
      tags:
      - System
      summary: Deprecated alias of /api/v1/control/plane/reconcile
      operationId: postApiControlPlaneReconcile
      x-operation-id-source: derived
  /api/capabilities:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/capabilities
      operationId: getApiCapabilities
      x-operation-id-source: derived
  /api/capabilities/graph:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/capabilities/graph
      operationId: getApiCapabilitiesGraph
      x-operation-id-source: derived
  /api/capabilities/graph/{version}:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/capabilities/graph/{version}
      operationId: getApiCapabilitiesGraphByVersion
      x-operation-id-source: derived
  /api/contracts/dual-plane:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/contracts/dual-plane
      operationId: getApiContractsDualPlane
      x-operation-id-source: derived
  /api/contracts/dual-plane/errors:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/contracts/dual-plane/errors
      operationId: getApiContractsDualPlaneErrors
      x-operation-id-source: derived
  /api/openapi:
    get:
      tags:
      - System
      summary: Deprecated alias of /api/v1/openapi
      operationId: getApiOpenapi
      x-operation-id-source: derived
  /api/maintenance/payload-ttl/prune:
    post:
      tags:
      - System
      summary: Deprecated alias of /api/v1/maintenance/payload-ttl/prune
      operationId: postApiMaintenancePayloadTtlPrune
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    agentHeader:
      type: apiKey
      in: header
      name: x-agent-id