DocsBook a demo

Platform

Platform overviewArchitectureWorkflow orchestrationGitOps configurationGovernance and AAAAI and MCPKnowledge and contextRuntime and executionEvidence and monitoring

Use cases

All use casesProduction incidentRelease preparationHotfix to productionSecurity scan triage
Why NopsAIIntegrationsSecurity

Resources

All resourcesAI agent governanceMCP governanceMCP securitySelf-hosted platforms
PricingGitHub

Company

How a run worksAboutContactBook a demo

Internal service routes

Component-to-component traffic: what calls each route, why it exists, and why none of it is a public surface.

ReferenceDeveloperOperatorSecurity

Key points

  • These routes are documented at contract depth: caller, purpose, and boundary, with no call samples.
  • Calling them by hand corrupts run state rather than integrating with the platform.
  • logs/ingest, the task status route, and finalize sit under /v1/runs/ rather than /v1/internal/, so they look public in a route list while being agent-only.
  • The runtime-config watch is why a PUT /v1/system/config takes effect without restarting services.
  • The approval pause route is what makes a checkpoint durable: the run becomes a record rather than a held process.
  • AI usage records reported here are the source of the numbers in the monitoring AI usage view.

Operations

GET/internal/v1/runtime-config/{service}Service token

Runtime configuration a platform service pulls at startup.

Notes

Called by aaa, dispatcher, git-bot, and the agent as they start. Not a public API: the shape follows whatever those services need and changes with them.

Side effects

  • None. The caller reads its own configuration.

Proven by

  • services/nopsai/runtime_config_api.go
GET/internal/v1/runtime-config/{service}/watchService token

Long-lived watch that pushes runtime configuration changes to a service.

Notes

This is why a configuration change through PUT /v1/system/config takes effect without restarting services. Not a public API.

Streaming

text/event-stream - Long-lived connection; the service receives a message when its configuration changes.

Side effects

  • Holds an open connection for the lifetime of the calling service.

Proven by

  • services/nopsai/runtime_config_api.go
POST/v1/internal/config/syncService token

Internal trigger for a configuration sync.

Notes

Used by platform components that need to force a sync. Operators should use POST /v1/system/config/sync instead, which is authorized and audited as an operator action.

Side effects

  • Starts a configuration sync.

Proven by

  • services/nopsai/config_sync.go
GET/v1/internal/dispatcher/routingAuthenticated

Routing table the dispatcher uses to match work to runner scopes.

Notes

Read by the dispatcher. The operator-facing equivalents are GET /v1/system/dispatcher for the live fleet and GET /v1/system/dispatcher/scopes for advertised scopes.

Side effects

  • None.

Proven by

  • services/nopsai/routes.go
  • services/nopsai/aaa_helpers.go
GET/v1/internal/git-bot/bootstrapService token

Bootstrap configuration git-bot needs to start handling provider webhooks.

Notes

Called by git-bot only. It carries GitHub App material, which is why it is service-gated rather than authorized.

Side effects

  • None.

Proven by

  • services/nopsai/routes.go
  • doc/git-apps.md
GET/v1/internal/git-bot/installationsService token

GitHub App installations git-bot may act for.

Notes

Called by git-bot when routing a delivery to the right installation. The operator-facing list is GET /v1/git-apps/github/installations.

Side effects

  • None.

Proven by

  • services/nopsai/routes.go
  • doc/git-apps.md
POST/v1/internal/runs/{runID}/ai-usageService token

Records the token usage of one LLM call against a run.

Notes

Reported by the per-run agent as it works. This is where the numbers in GET /v1/monitoring/ai-usage come from.

Side effects

  • Appends an AI usage record to the run.

Proven by

  • services/nopsai/ai_usage_handlers.go
POST/v1/internal/runs/{runID}/approvals/pauseService token

Pauses a run at an approval checkpoint and releases its runner capacity.

Notes

Called by the agent when it reaches an approval step. This is the mechanism that makes a checkpoint durable: the run becomes a record rather than a held process.

Side effects

  • Creates the pending approval and releases the runner slot the run held.

Proven by

  • services/nopsai/approval_handlers.go
GET/v1/internal/runs/{runID}/checkpoints/{checkpointID}Service token

Reads the checkpoint state an agent needs to resume after an approval.

Notes

Called by the agent when a paused run is picked up again, possibly by a different runner than the one that paused it.

Side effects

  • None.

Proven by

  • services/nopsai/approval_handlers.go
GET/v1/internal/runs/{runID}/policy-revisionService token

The governance and knowledge policy revision pinned to a run.

Notes

Called by the agent so a long run keeps evaluating against the policy it started with rather than one edited mid-flight.

Side effects

  • None.

Proven by

  • services/nopsai/routes.go
POST/v1/internal/runs/{runID}/steps/{stepName}/tasks/{taskName}/outputsService token

Records the runtime outputs a task produced.

Notes

Called by the agent after a task writes files under /nopsai/outputs. This is what makes $steps.<step>.<task>.outputs.<NAME> resolvable downstream.

Side effects

  • Stores the output values, masking any declared sensitive.

Proven by

  • services/agent/internal/app/runtime_outputs.go
POST/v1/internal/runs/{runID}/task-outputs/resolveService token

Resolves outputs published by a synchronous child pipeline run.

Notes

Called by a parent run’s agent to read a child run’s outputs. It is the mechanism behind sync: true on a pipeline: include.

Side effects

  • None.

Proven by

  • services/agent/nopsai_client.go
POST/v1/runs/{runID}/logs/ingestService token

Streams run log lines from the agent into durable storage.

Notes

Agent-only despite sitting under /v1/runs/ rather than /v1/internal/. Read logs with GET /v1/runs/{runID}/logs; writing them by hand corrupts a run’s record.

Side effects

  • Appends log lines to the run, applying secret redaction on the way in.

Proven by

  • services/nopsai/run_internal_handlers.go
POST/v1/runs/{runID}/steps/{stepName}/tasks/{taskName}Service token

Reports a task’s status transition.

Notes

Agent-only, and the source of the per-step and per-task state shown in run detail. It sits under the public run path but is not part of the public surface.

Side effects

  • Advances the run graph and may complete or fail the run.

Proven by

  • services/nopsai/run_handlers.go
POST/v1/runs/{runID}/finalizeService token

Closes a run and starts final output generation.

Notes

Agent-only. It is what moves a run to its terminal status and queues the deliverables; calling it by hand ends a run that has not finished.

Side effects

  • Sets the terminal run status and queues final output generation.

Proven by

  • services/nopsai/run_handlers.go

How it works

Every route here has a public counterpart to reach for instead. Read logs with GET /v1/runs/{runID}/logs, not the ingest route. Sync configuration with POST /v1/system/config/sync, not the internal trigger. Inspect the fleet with GET /v1/system/dispatcher, not the routing table. The internal form exists for a component that already holds a service token and a specific job.

The three routes under /v1/runs/ are the ones worth knowing about, because a route list makes them look like part of the public API. They advance the run graph: ingesting logs, transitioning a task, and finalising a run. Calling any of them by hand ends up with a run whose recorded state does not match what happened.

This page exists so the surface is complete rather than to invite use. If an integration seems to need one of these routes, the public equivalent is almost always the right answer.

Implementation evidence

  • services/nopsai/run_internal_handlers.go

    Agent log ingest and run status reporting.

  • services/nopsai/runtime_config_api.go

    Runtime configuration pull and watch.

  • services/nopsai/aaa_helpers.go

    Which internal paths are authenticated rather than authorized.