1845e069e0
- Add SYSTEM_PROMPT.md with full documentation philosophy - Add STYLE_GUIDE.md with detailed writing standards - Create services/ directory with docs for API, Operator, Core, Web, Prism, Infra - Create agents/ directory with agent ecosystem documentation - Create guides/ directory with getting-started and contributing guides - Create runbooks/ directory with incident playbook and deployment runbooks - Create reference/ directory with API reference placeholder - Update sidebars.ts to include all new sections - Update CONTRIBUTING.md to reference new comprehensive guides - Update .gitignore to exclude binary assets per system prompt requirements - All documentation builds successfully with no broken links Co-authored-by: blackboxprogramming <118287761+blackboxprogramming@users.noreply.github.com>
100 lines
2.3 KiB
Markdown
100 lines
2.3 KiB
Markdown
---
|
|
id: reference-api-surface
|
|
title: "API Reference"
|
|
slug: /reference/api-surface
|
|
description: "Complete API reference for BlackRoad OS"
|
|
tags: ["reference", "api"]
|
|
status: planned
|
|
---
|
|
|
|
# API Reference
|
|
|
|
> 🚧 **Status:** This is a planned document. Detailed API reference is being developed.
|
|
|
|
Complete API reference documentation for BlackRoad OS services.
|
|
|
|
## Overview
|
|
|
|
This page will provide comprehensive API documentation including:
|
|
|
|
- Authentication and authorization
|
|
- Endpoint specifications
|
|
- Request/response schemas
|
|
- Error codes and handling
|
|
- Rate limiting
|
|
- Webhooks and events
|
|
|
|
## Planned Sections
|
|
|
|
### Authentication
|
|
|
|
- PS-SHA∞ identity verification
|
|
- JWT token authentication
|
|
- API key authentication
|
|
- OAuth integration (if supported)
|
|
|
|
### Core Endpoints
|
|
|
|
#### Agents
|
|
- `GET /api/v1/agents` - List agents
|
|
- `POST /api/v1/agents` - Create agent
|
|
- `GET /api/v1/agents/:id` - Get agent
|
|
- `PATCH /api/v1/agents/:id` - Update agent
|
|
- `DELETE /api/v1/agents/:id` - Delete agent
|
|
|
|
#### Jobs
|
|
- `GET /api/v1/jobs` - List jobs
|
|
- `POST /api/v1/jobs` - Submit job
|
|
- `GET /api/v1/jobs/:id` - Get job status
|
|
- `DELETE /api/v1/jobs/:id` - Cancel job
|
|
|
|
#### Events
|
|
- `GET /api/v1/events` - List events
|
|
- `POST /api/v1/events/subscribe` - Subscribe to events
|
|
- `DELETE /api/v1/events/unsubscribe` - Unsubscribe
|
|
|
|
### Error Codes
|
|
|
|
Standard HTTP status codes plus BlackRoad-specific error codes.
|
|
|
|
### Rate Limiting
|
|
|
|
API rate limits and quotas.
|
|
|
|
### Webhooks
|
|
|
|
Webhook configuration and event types.
|
|
|
|
## Current Resources
|
|
|
|
For now, please refer to:
|
|
|
|
- [API Overview](dev/API_OVERVIEW.md) - High-level API concepts
|
|
- [Service: API](services/service-api.md) - API service documentation
|
|
- [Core Primitives](dev/CORE_PRIMITIVES.md) - Data models
|
|
|
|
## OpenAPI Specification
|
|
|
|
> 📋 **Coming Soon:** OpenAPI/Swagger specification will be published.
|
|
|
|
## SDKs and Client Libraries
|
|
|
|
> 📋 **Coming Soon:** Official client libraries for various languages.
|
|
|
|
## Contributing
|
|
|
|
To help build this API reference:
|
|
|
|
1. Review existing API endpoints in the codebase
|
|
2. Document request/response formats
|
|
3. Add examples and error cases
|
|
4. Submit PR to update this document
|
|
|
|
See [Contributing Guide](guides/contributing.md).
|
|
|
|
## See Also
|
|
|
|
- [Service: API](services/service-api.md)
|
|
- [Core Primitives](dev/CORE_PRIMITIVES.md)
|
|
- [Events and RoadChain](dev/EVENTS_AND_ROADCHAIN.md)
|