Cyiro
Sign InRequest access

Docs center

Self-hosted docs for Guardrails for AI.

Technical guidance for observability, guardrails, permissioning, and automation in one first-party documentation surface.

Self-hosted docs

API Contracts

Integrate runtime events and control surfaces with stable API contracts.

docs.cyiro.comproduction-ready guidance

Event ingestion endpoints

Send runtime and change payloads with deterministic identifiers so downstream correlation remains reliable.

  • Example: POST /v1/ingest/runtime with route_id, event_id, timestamp
  • Example: POST /v1/ingest/change with provider, change_id, classification
  • Example: Use idempotency keys for exactly-once processing

Control plane APIs

Manage guardrail policies, alert rules, and delivery targets through workspace-scoped endpoints.

  • Example: GET /v1/workspaces/:id/policies for policy list
  • Example: POST /v1/workspaces/:id/alert-rules to create new rule
  • Example: PUT /v1/workspaces/:id/deliveries/:targetId to update target

Failover policies API

Configure automatic failover rules and fallback endpoints for production routes.

  • Example request: POST /v1/workspaces/:id/failover-policies {route_id: "prod-chat", primary_endpoint: "anthropic-claude", fallback_endpoints: ["bedrock-claude"], conditions: {latency_threshold_ms: 2000, error_rate_threshold: 0.1}}
  • Example response: {id: "failover-123", status: "active", route_id: "prod-chat", fallback_endpoints: [{"id": "bedrock-claude", "status": "healthy"}]}
  • Example: GET /v1/workspaces/:id/failover-policies to list all policies
  • Example: DELETE /v1/workspaces/:id/failover-policies/:policyId to remove a policy

Alert rules API

Define when and how to notify teams about runtime and policy events.

  • Example: POST /v1/workspaces/:id/alert-rules {name: "High Latency", condition: {metric: "latency", threshold_ms: 3000, window_seconds: 300}, delivery_targets: ["slack-devops", "email-oncall"], severity: "high"}
  • Example: GET /v1/workspaces/:id/alert-rules to list all active rules
  • Example: PUT /v1/workspaces/:id/alert-rules/:ruleId to update thresholds
  • Example: POST /v1/workspaces/:id/alert-rules/:ruleId/test to trigger test alert

Delivery targets API

Configure where alerts and digests are sent across your organization.

  • Example: POST /v1/workspaces/:id/deliveries {name: "Slack DevOps", type: "slack", config: {webhook_url: "https://hooks.slack.com/...", channel: "#ai-ops"}, default_severity: "medium"}
  • Example: GET /v1/workspaces/:id/deliveries to list all targets
  • Example: POST /v1/workspaces/:id/deliveries/:targetId/verify to test configuration
  • Example: DELETE /v1/workspaces/:id/deliveries/:targetId to remove a target

Incidents API

Retrieve and manage incident data with full context and correlation.

  • Example: GET /v1/workspaces/:id/incidents to list recent incidents
  • Example: GET /v1/workspaces/:id/incidents/:incidentId for detailed incident timeline
  • Example response includes: incident_id, status, severity, created_at, updated_at, related_events[], policy_violations[], failover_actions[]
  • Example: POST /v1/workspaces/:id/incidents/:incidentId/notes to add context

API behavior and contracts

Error handling, rate limiting, and data consistency guarantees.

  • Auth errors: 401 Unauthorized for missing/invalid tokens, 403 Forbidden for insufficient permissions
  • Validation errors: 422 Unprocessable Entity with field-specific error messages
  • Rate limits: Standard headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
  • Idempotency: Use Idempotency-Key header for exactly-once processing on ingest endpoints
  • Pagination: ?page=1&limit=50 with Link header for navigation, default limit: 25, max: 100
  • Sorting: ?sort=created_at:desc or ?sort=severity:asc on list endpoints
  • Filtering: ?status=active&severity=high on incidents and alerts

Schema compatibility

Versioning and evolution policies for API contracts.

  • Enum stability: Existing enum values never removed, new values added as optional
  • Migration compatibility: Schema versions maintained for 6 months with deprecation warnings
  • Deprecation policy: Fields marked deprecated for 3 months before removal, announced in changelog
  • Field deprecation template: "DEPRECATED: Use new_field instead. Will be removed in v2.1.0"