planning v1

AI-friendly cloud control plane.

AI-first neocloud control plane for agents, Terraform, CLIs, and UI clients building on LinkRidge Cloud.

The checked OpenAPI 3.1 skeleton lives in docs/api/linkridge-cloud-control-plane.openapi.json and is validated against this resource model.

API version v1

All agent, UI, CLI, MCP, and Terraform clients should converge on this control-plane contract.

Base path /v1

The repo now keeps an OpenAPI skeleton aligned with these paths before backend, SDK, and provider work grows from it.

Beta footprint mfsoho

Limited hardware capacity means beta services must be quota-aware, approval-gated, and biased toward control-plane proof before heavy data-plane workloads.

Neocloud thesis

Use AWS control-plane discipline without inheriting AWS scale complexity.

OpenAPI is the source of truth for every public control-plane resource.
Agents and Terraform call the same API as the UI instead of using separate backdoors.
Every write is idempotent, auditable, tenant-scoped, and able to run in dry-run mode before external effects.
Small-cluster beta limits are explicit until the larger 155/Dell footprint is available.
AWS-style separation of control plane and data plane guides the architecture without copying AWS complexity.

API conventions

Agents need predictable contracts more than clever endpoints.

Stable resource IDs: Every resource exposes an immutable id and a type-specific import path for agents, Terraform, and audit logs.
Idempotency keys: Mutating POST requests accept Idempotency-Key and return the original result for safe agent retries.
Dry-run planning: Risky writes support dry_run=true or a plan endpoint that returns intended effects without executing them.
Explicit states: Long-running and approval-gated resources expose status, blockers, and next_allowed_actions.
Pagination: List endpoints use cursor pagination with deterministic ordering and predictable page limits.
Problem errors: Errors follow application/problem+json with code, message, request_id, and remediation fields.
Audit events: Every state-changing request emits or references an audit event with actor, account, service, target, and action context.
Account-scoped writes: Account-scoped internal/dev tokens may prepare only resources for allowed accounts; draft account creation requires wildcard operator scope.
Webhooks: Async state changes can emit signed webhook events after the platform webhook primitive exists.

identity

Identity and tenancy

Accounts, users, memberships, invites, roles, and service tokens.

auth_diagnostics: /v1/auth/diagnostics
auth_token_policy: /v1/auth/token-policy
account_auth_token_policy: /v1/accounts/{account_id}/auth/token-policy
accounts: /v1/accounts
account_memberships: /v1/accounts/{account_id}/memberships
account_invites: /v1/accounts/{account_id}/invites
service_tokens: /v1/accounts/{account_id}/service-tokens

service_catalog

Service catalog

Available services, plans, entitlements, account services, and usage limits.

services: /v1/services
account_services: /v1/accounts/{account_id}/services
entitlements: /v1/accounts/{account_id}/services/{account_service_id}/entitlements

qr_service

QR service

QR workspaces, campaigns, codes, mutation requests, route resolution, scan events, and audit evidence.

qr_workspaces: /v1/qr/workspaces
qr_campaigns: /v1/qr/workspaces/{workspace_id}/campaigns
qr_codes: /v1/qr/workspaces/{workspace_id}/codes
qr_mutation_requests: /v1/qr/workspaces/{workspace_id}/mutation-requests
qr_mutation_request_readback: /v1/qr/workspaces/{workspace_id}/mutation-requests/{mutation_request_id}
qr_mutation_execution_rehearsal_requirements: /v1/qr/workspaces/{workspace_id}/mutation-requests/{mutation_request_id}/execution-rehearsal-requirements
qr_route_resolutions: /v1/qr/workspaces/{workspace_id}/route-resolutions
qr_import_jobs: /v1/qr/workspaces/{workspace_id}/import-jobs
qr_scan_events: /v1/qr/workspaces/{workspace_id}/scan-events

operations

Operations

Provisioning runs, operator approvals, billing export requests, audit records, and status checks.

activation_packets: /v1/accounts/{account_id}/services/{account_service_id}/activation-packets
billing_export_requests: /v1/accounts/{account_id}/services/{account_service_id}/billing-export-requests
support_cases: /v1/accounts/{account_id}/services/{account_service_id}/support-cases
provisioning_runs: /v1/provisioning-runs
review_packets: /v1/review-packets
review_packet_decisions: /v1/review-packets/{review_packet_id}/decision
review_packet_decision_requirements: /v1/review-packets/{review_packet_id}/decision-requirements
operator_approvals: /v1/operator-approvals
audit_events: /v1/audit-events

future_primitives

Future primitives

Workflow runs, function deployments, app deployments, object buckets, domains, queues, and schedules.

workflow_runs: /v1/workflows/runs
function_deployments: /v1/functions
app_deployments: /v1/deployments
object_buckets: /v1/storage/buckets

Provider design rules

Terraform should plan first and execute only through reviewed API writes.

Provider resources map one-to-one to durable control-plane resources.
Data sources expose catalog, entitlement, approval, provisioning, and audit state.
Create and update operations send Idempotency-Key and preserve request_id/audit_event_id in diagnostics.
Plan-time validation calls dry-run endpoints when a change could trigger billing, invites, DNS, deploys, or external redirects.
Import IDs follow stable API resource IDs rather than display names.

Control-plane resources

One API model for agents, Terraform, MCP, CLI, and UI.

identity GET

auth_diagnostics

Authenticated internal/dev token diagnostics for accepted actor, scope, account-scope allowlist, actor-binding fingerprint, configured-token state, scope-config validity, and guardrail evidence.

Path: /v1/auth/diagnostics
Terraform: linkridgecloud_auth_diagnostics

Returns only non-secret actor, scope, account-scope allowlist, actor-binding fingerprint, configured-token/default-dev-fallback evidence, scope-config validity, account-scope config validity, and guardrail metadata for the accepted bearer token; it must never return token values, token hashes, token-material fingerprints, customer credentials, service-token secret material, or external auth-provider state. Unsupported configured scopes and unsafe wildcard-plus-account allowlists fail closed before authenticated API access.

identity GET

auth_token_policy

Read-only internal/dev contract for planned operator API keys, customer service-token credentials, and actor-binding evidence.

Path: /v1/auth/token-policy
Terraform: linkridgecloud_auth_token_policy

Documents account binding, actor-binding fingerprints, allowed internal/dev scopes, hashing, rotation, revocation, Terraform usage, configured-token/default-dev-fallback runtime evidence, scope-config validity, account-scope config validity, approval requirements, and disabled credential issuance without returning token values, token hashes, token-material fingerprints, service-token secret material, external API access, or auth-provider state.

identity GET

account_auth_token_policy

Account-scoped read-only token policy evidence for tenant-bound operator and customer automation credentials.

Path: /v1/accounts/{account_id}/auth/token-policy
Terraform: linkridgecloud_auth_token_policy

Verifies account existence and actor account scope before returning planned token policy metadata and non-secret actor-binding evidence; it denies cross-account reads and never issues credentials, stores token hashes, returns token material, or enables external API access.

identity GET, POST

accounts

Tenant and billing boundary for one customer or builder workspace.

Path: /v1/accounts
Terraform: linkridgecloud_account

Agents may list and prepare draft accounts, but activation remains approval-gated. Account-scoped internal/dev tokens can list allowed accounts only; draft account creation requires wildcard operator scope.

identity GET, POST

account_memberships

Account-scoped role assignment for users or approved agent operators.

Path: /v1/accounts/{account_id}/memberships
Terraform: linkridgecloud_account_membership

Account-scoped internal/dev tokens may only read memberships for their allowed accounts. Invite delivery is separate from local membership planning.

identity GET, POST

account_invites

Draft account invite packets with role, service scope, expiry, and delivery state.

Path: /v1/accounts/{account_id}/invites
Terraform: linkridgecloud_account_invite

Account-scoped internal/dev tokens may only read or prepare invite metadata for their allowed accounts. Invite records may be prepared for review, but outbound delivery and external access require explicit approval.

identity GET, POST

service_tokens

Scoped API credentials for approved automation clients.

Path: /v1/accounts/{account_id}/service-tokens
Terraform: linkridgecloud_service_token

Account-scoped internal/dev tokens may only read or prepare service-token metadata for their allowed accounts. The local/dev runtime can prepare service-token metadata requests and review packets, but secret issuance, token-hash storage, external API access, invites, and billing exports stay approval-gated.

service_catalog GET

services

Catalog of LinkRidge Cloud services and lifecycle state.

Path: /v1/services
Terraform: linkridgecloud_service

Read-only discovery endpoint for agent service selection.

service_catalog GET, POST

account_services

Requested or enabled service subscriptions for an account.

Path: /v1/accounts/{account_id}/services
Terraform: linkridgecloud_account_service

Account-scoped internal/dev tokens may only read or prepare account-service records for their allowed accounts. The local/dev runtime can prepare draft service activation requests, but activation, billing, workspace creation, token secrets, customer access, and hosted QR redirects stay approval-gated.

service_catalog GET

entitlements

Effective feature and limit values for one account service.

Path: /v1/accounts/{account_id}/services/{account_service_id}/entitlements
Terraform: linkridgecloud_entitlements

Account-scoped internal/dev tokens may only read entitlement records for their allowed accounts. Agents should read entitlements before performing tenant work.

operations GET, POST

activation_packets

Operator review packet that ties account identity, membership, entitlements, service workspace, billing boundary, skipped external actions, and audit evidence together before activation.

Path: /v1/accounts/{account_id}/services/{account_service_id}/activation-packets
Terraform: linkridgecloud_activation_packets

Account-scoped internal/dev tokens may only read or prepare activation packets for their allowed accounts. The local/dev runtime can prepare activation packets for review, but agents must not activate accounts, send invites, issue credentials, bill, expose redirects, or deploy production changes.

qr_service GET, POST

qr_workspaces

Tenant-scoped QR service workspace resolved before QR records load.

Path: /v1/qr/workspaces
Terraform: linkridgecloud_qr_workspace

Account-scoped internal/dev tokens only list or prepare QR workspaces for their allowed accounts. The local/dev runtime can prepare planned QR workspaces for an existing QR account service, but redirects, imports, dashboards, mutations, and billable usage stay approval-gated.

qr_service GET, POST

qr_campaigns

Campaign grouping for QR codes and scan evidence.

Path: /v1/qr/workspaces/{workspace_id}/campaigns
Terraform: linkridgecloud_qr_campaign

Campaign IDs must remain workspace-scoped.

qr_service GET, POST

qr_codes

Managed QR code records with destination, slug, label, style, and status.

Path: /v1/qr/workspaces/{workspace_id}/codes
Terraform: linkridgecloud_qr_code

Destination changes should use mutation requests when external redirects are gated.

qr_service GET, POST

qr_mutation_requests

Planned QR changes that require entitlement checks and operator approval before external effects.

Path: /v1/qr/workspaces/{workspace_id}/mutation-requests
Terraform: linkridgecloud_qr_mutation_request

Account-scoped internal/dev tokens may only read mutation requests for workspaces bound to their allowed accounts. Agent writes should prefer mutation requests for reviewable changes.

qr_service GET

qr_mutation_request_readback

Exact account-scoped readback for a planned QR mutation request and its sanitized readiness evidence.

Path: /v1/qr/workspaces/{workspace_id}/mutation-requests/{mutation_request_id}
Terraform: linkridgecloud_qr_mutation_requests

Operators can use this after draft POST to prove the persisted request, review status, draft idempotency evidence, and no-effect guardrails without relying on list filtering. This route never exposes idempotency keys, request hashes, token values, hosted redirects, billing usage, or customer-visible write effects.

qr_service GET

qr_mutation_execution_rehearsal_requirements

Read-only checklist and safe request template for the dev-only QR mutation execution rehearsal.

Path: /v1/qr/workspaces/{workspace_id}/mutation-requests/{mutation_request_id}/execution-rehearsal-requirements
Terraform: linkridgecloud_qr_mutation_requests

Operators and Terraform can inspect whether a QR mutation has the required approved_local_only review decision, the exact blocked-action acknowledgement set, the actor binding fingerprint, a rehearsal_requirements_fingerprint that must be echoed by the POST body, non-secret idempotency requirements, and any existing rehearsal evidence before posting execution-rehearsal. This endpoint never writes tenant QR records, enables redirects, checks entitlement, records billing usage, or creates customer-visible effects.

qr_service GET

qr_route_resolutions

Account-scoped redirect resolution evidence for QR slugs before hosted redirects are approved.

Path: /v1/qr/workspaces/{workspace_id}/route-resolutions
Terraform: linkridgecloud_qr_route_resolutions

Agents should inspect route evidence before proposing hosted redirect or destination-change work.

qr_service GET, POST

qr_import_jobs

Reviewable import plans for Open QR browser libraries or links.json exports before tenant records are changed.

Path: /v1/qr/workspaces/{workspace_id}/import-jobs
Terraform: linkridgecloud_qr_import_job

Account-scoped internal/dev tokens may only read or prepare import jobs for workspaces bound to their allowed accounts. Import jobs must reconcile slugs, aliases, and destinations locally while customer data import, redirects, and external writes stay approval-gated.

qr_service GET

qr_scan_events

Local-only QR scan usage evidence resolved through account, account service, workspace, and code context.

Path: /v1/qr/workspaces/{workspace_id}/scan-events
Terraform: linkridgecloud_qr_scan_events

Fixture scan events stay non-billable and unexported until hosted redirects and billing export are approved.

operations GET, POST

billing_export_requests

Reviewable export requests that group service usage before any external billing-provider write occurs.

Path: /v1/accounts/{account_id}/services/{account_service_id}/billing-export-requests
Terraform: linkridgecloud_billing_export_request

Account-scoped internal/dev tokens may only read billing export requests for their allowed accounts. Writes stay approval-gated and must not create customers, subscriptions, invoices, or metered usage records without explicit approval.

operations GET, POST

support_cases

Reviewable support and operator-handoff cases tied to one account service before customer-visible support workflows exist.

Path: /v1/accounts/{account_id}/services/{account_service_id}/support-cases
Terraform: linkridgecloud_support_case

Account-scoped internal/dev tokens may only read support cases for their allowed accounts. Agents may prepare local support evidence, but outbound customer contact, ticket creation, and escalation actions require explicit approval.

operations GET, POST

provisioning_runs

Local rehearsal and future execution record for account-service provisioning.

Path: /v1/provisioning-runs
Terraform: linkridgecloud_provisioning_run

Supports dry-run planning and records skipped external actions.

operations GET

review_packets

Normalized internal review index for blocked service-token, import, activation, billing, and support packets.

Path: /v1/review-packets
Terraform: linkridgecloud_review_packets

Read-only operator evidence for approval-gated work. Account-scoped internal/dev tokens may only read packets for their allowed accounts; this endpoint must not approve, execute, notify, export, issue secrets, or enable customer-visible effects.

operations POST

review_packet_decisions

Internal-only approve/reject decision transition for one review packet.

Path: /v1/review-packets/{review_packet_id}/decision
Terraform: linkridgecloud_review_packets

Local approval requires the accepted internal/dev actor to be scoped to the review packet account, the linked local/dev resource to be present, external_effects_acknowledged=true, blocked_external_actions_acknowledged to list all and only the current skipped actions, and decision_requirements_fingerprint from the current requirements response/template before state is persisted. Missing, invalid, or stale fingerprints fail closed before idempotency, audit, or state writes. Decisions update evidence, retain the accepted/current decision_requirements_fingerprint, store normalized guardrail_evidence and non-secret operator_evidence with linked resource transition evidence on the review packet/operator approval/audit record, and may mark linked invite, service-token, QR import, QR mutation, activation, billing-export, or support metadata ready_for_review/open_local_only while delivery, secrets, import execution, redirects, billing export, support tickets, activation, customer access, and production deploys remain blocked; exact idempotent replays are allowed, but a fresh decision against an already approved/rejected packet fails closed; it does not create customer-visible effects.

operations GET

review_packet_decision_requirements

Read-only checklist and safe decision body templates for the local-only approve/reject body required by one review packet.

Path: /v1/review-packets/{review_packet_id}/decision-requirements
Terraform: linkridgecloud_review_packets

Operators and Terraform can inspect the exact blocked_external_actions acknowledgement set, required decision_requirements_fingerprint, ready-to-use approve_local_only/reject body templates, optional reviewer_user_id/operator_notes evidence fields that become normalized non-secret operator_evidence, linked-resource readiness, linked transition preview, actor binding fingerprint, non-secret idempotency requirements, and local-only guardrails before posting a decision. The transition preview names the linked local resource, approve/reject resulting statuses, next required operator action, and disabled external-effect flags without mutating state. Posted acknowledgements must match all and only the current blocked-action set, and posted fingerprints must match the current packet status, actor binding, linked-resource readiness, and blocked-action set. Already approved/rejected packets return decision_allowed=false, decision_blocked_reason=review_packet_already_decided, empty required_body_fields/optional_body_fields, and no decision_templates so operators cannot accidentally reuse a terminal packet checklist. Terminal packets also return terminal_decision with the accepted fingerprint, non-secret reviewer/note metadata, linked-resource transition evidence, idempotency evidence, and guardrails while external effects remain explicitly false. This endpoint is account-scoped and never approves, rejects, executes, notifies, exports, issues secrets, writes token hashes, enables redirects, or creates customer-visible effects.

operations GET

operator_approvals

Read-only approval decision records created by review-packet decisions.

Path: /v1/operator-approvals
Terraform: linkridgecloud_operator_approval

Operator approval records are evidence only. Local-only approve/reject writes must use /v1/review-packets/{review_packet_id}/decision with acknowledgement evidence. The read model includes the accepted decision_requirements_fingerprint, normalized non-secret operator_evidence with linked resource type, resulting status, next required operator action, and skipped-effect flags, guardrail_evidence, and trimmed operator notes from file and Postgres backing stores; direct operator-approval writes stay disabled, and external execution still requires explicit Matthew approval.

operations GET

audit_events

Append-only platform and service history for support, review, and compliance.

Path: /v1/audit-events
Terraform: linkridgecloud_audit_events

Agents should preserve audit_event_id returned by mutating calls.

future_primitives GET, POST

workflow_runs

Step Functions-like workflow executions, initially backed by n8n or a small native runner.

Path: /v1/workflows/runs
Terraform: linkridgecloud_workflow

Future primitive; keep API shape AWS-inspired and implementation pluggable.

future_primitives GET, POST

function_deployments

Lambda-like function packages for event or HTTP execution.

Path: /v1/functions
Terraform: linkridgecloud_function

Future primitive; beta scope depends on cluster capacity and isolation model.

future_primitives GET, POST

app_deployments

Vercel-like site/app deployment records with preview and production promotion states.

Path: /v1/deployments
Terraform: linkridgecloud_deployment

Future primitive; should reuse existing static-site deploy knowledge.

future_primitives GET, POST

object_buckets

S3-compatible bucket provisioning and account-scoped storage policy.

Path: /v1/storage/buckets
Terraform: linkridgecloud_bucket

Future primitive; prefer S3 compatibility over a custom storage API.