blackroad-os-docs/docs/services/service-api.md

id, title, slug, description, tags, status

id	title	slug	description	tags	status
services-service-api	Service: API	/services/service-api	Documentation for the BlackRoad OS API service	services api	stable

Service: API

What it does

The BlackRoad OS API is the primary HTTP gateway for the BlackRoad OS ecosystem. It provides RESTful endpoints for:

• Agent management and orchestration
• Job submission and monitoring
• Identity and authentication via PS-SHA∞
• Event streaming and subscriptions
• Integration with external systems

Repository

• GitHub: BlackRoad-OS/blackroad-os-api
• Primary Language: TypeScript (Node.js)
• Framework: Express / Fastify

Key Features

• 🔐 PS-SHA∞ identity authentication
• 🤖 Agent lifecycle management
• 📊 Real-time event streaming
• 🔄 Job queue integration with Operator
• 📝 Comprehensive request/response logging
• ⚡ High-performance async operations

Architecture

flowchart LR
    Client[Client/Web] --> API[API Service]
    API --> Core[Core Service]
    API --> Operator[Operator Service]
    API --> DB[(Database)]
    Operator --> Queue[Job Queue]

Deployment

The API service is deployed using:

• Platform: Railway
• Environment Variables: See .env.example in the repository
• Health Checks: /health, /ready, /version

For deployment procedures, see:

• Infra Guide
• Deploy API Runbook (planned)

Health Checks

Standard endpoints:

Endpoint	Purpose	Expected Response
GET /health	Basic health check	200 OK with { status: "healthy" }
GET /ready	Readiness check (DB connected)	200 OK when ready
GET /version	Service version info	200 OK with version details

Key Endpoints

Authentication

• POST /auth/login - User/agent authentication
• POST /auth/refresh - Token refresh
• POST /auth/verify - Verify PS-SHA∞ signature

Agents

• GET /agents - List agents
• POST /agents - Create new agent
• GET /agents/:id - Get agent details
• PATCH /agents/:id - Update agent
• DELETE /agents/:id - Deactivate agent

Jobs

• GET /jobs - List jobs
• POST /jobs - Submit new job
• GET /jobs/:id - Get job status
• DELETE /jobs/:id - Cancel job

For complete API reference, see API Surface (planned).

Related Services

• Service: Core - Core domain logic and data models
• Service: Operator - Job orchestration and execution
• Service: Prism Console - Monitoring and observability UI
• Service: Web - User-facing web application

Environment Configuration

Key environment variables (see repository for complete list):

• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection for sessions/cache
• API_PORT - Port to listen on (default: 3000)
• JWT_SECRET - Secret for JWT signing
• OPERATOR_URL - URL of Operator service

⚠️ Security: Never commit actual values. Use Railway secrets or equivalent.

Development

Local development setup:

# Clone the repository
git clone https://github.com/BlackRoad-OS/blackroad-os-api.git
cd blackroad-os-api

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with local values

# Run in development mode
npm run dev

See Local Development Guide for more details.

Monitoring

• Logs: Available via Railway dashboard
• Metrics: Prometheus-compatible endpoints (if configured)
• Tracing: OpenTelemetry support (if configured)
• Dashboard: Prism Console

Troubleshooting

Common issues:

Service won't start

• Check environment variables are set correctly
• Verify database is accessible
• Check logs for connection errors

Slow response times

• Check database query performance
• Review Redis cache hit rates
• Check Operator service health

Authentication failures

• Verify JWT_SECRET is consistent across deployments
• Check token expiration settings
• Validate PS-SHA∞ signatures

For incident response, see Incident Playbook.

Contributing

To contribute to the API service:

1. Review Contributing Guide
2. Follow Coding Standards (planned)
3. Submit PRs to the repository
4. Ensure all tests pass

See Also

• API Overview - High-level API concepts
• Core Primitives - Data models and types
• Events and RoadChain - Event system