Forge — Platform Core

Forge is the platform's control plane: tenants, configuration, credentials, billing, and workflow tracking live here. It presents three surfaces with different maturity:

Portal API (Available)

Base URL: https://forge.dev.apex.reisiger.org. Two credential styles apply per operation (Authentication): portal sessions (your administrators, signed in to the portal) and machine-to-machine tokens (provisioning integrations).

Provisioning (machine-to-machine, scope forge/tenant.write): POST /api/tenants creates a tenant — the venture-factory path described in Tenancy & Onboarding. Idempotency-Key: provision:<uuid> makes retries replay-safe; 201 means complete, 202 + status URL means runtime resources are still provisioning (poll GET /api/tenants/{id}/provisioning).

Tenant administration (session): tenant detail and update, API keys (create — value shown once; rotate; revoke), per-product configuration (GET/PUT /api/tenants/{id}/products/{productId}/config), members, and Echo channel registrations.

Billing & usage (session): balances, budgets and alerts, invoices, rate card, cost series, and the transaction ledger — GET /api/tenants/{id}/billing/transactions filtered by period/product, and …/transactions/{correlationId} for the full per-model token and ZAR breakdown of one correlated transaction. This is the reconciliation surface described in Usage & Cost.

Workflows (session): definition CRUD plus run tracking (…/workflows/{workflowId}/runs) for operational visibility of your recurring processes.

Support service (Preview)

A tenant-scoped assistant and agent-execution surface, currently available in local/companion deployments; cloud availability is operator-arranged. Authenticates with a dedicated support-service token from your operator.

• Support conversations — POST /api/v1/query with page context; session history endpoints.
• Tool invocation — GET /api/v1/tools lists the tier-filtered manifest of APEX capabilities exposed as tools; POST /api/v1/tools/invoke calls one; POST /api/v1/tools/agent lets a goal-directed agent chain them (professional tier and above).
• Agent execution — POST /api/v1/agents/execute: your system prompt + user message + a tool list (APEX registry shorthands, web search, or inline tool definitions), with extended-thinking budgets. The response itemises token usage and apex_costs[] — every downstream APEX call the agent made, with per-call ZAR. Batch variant for up to 10 agents.
• Pipeline tracking — templates, runs, progress updates, and human gate decisions. Your application executes the pipeline; Forge tracks state for portal visibility, cost roll-up, and audit.
• Batch processing and proposal generation round out the surface — see the spec.

LLM gateway (Planned)

Contract pinned — not yet served. Build against the spec behind a flag or mock; do not point production traffic at it until your operator confirms launch. Until then, LLM dispatch is available to platform products only.

The committed path for model dispatch from your own agents, so you never embed vendor SDKs or keys:

• POST /api/v1/llm/messages — Anthropic-Messages-compatible: messages, system, tools, thinking; non-streaming or Server-Sent Events. Every response (and every stream, via a terminal apex_usage event) carries token counts and cost_zar, threaded by X-Correlation-ID.
• GET /api/v1/llm/models — the model catalog with provider and tier facets (flagship | balanced | fast | reasoning | code). Model choice is tenant configuration; treat the catalog as data, never hardcode model names.

Auth: Forge-issued tenant API key with scope llm:invoke.

Integration notes

• The portal API is your operators' surface; your application's runtime path is the products themselves plus (once live) the LLM gateway.
• Programmatic usage export is on the roadmap — billing reads are session-authenticated today (Usage & Cost).
• Configuration changes made here propagate to products without redeploys — design for entitlements changing between calls (tenancy rule 3).