Reference API Surface

Pool API Portal

A static reference contract for pools, members, policies, allocations, leases, usage events, and audit trails. The examples are conceptual—not live PoolAPI.com endpoints.

Contract first

A small set of durable objects

The portal organizes a reusable control plane around pools, members, policies, allocations, leases, usage events, and audit events. Specialized APIs add model routes, prompt versions, compute jobs, asset transfers, ballots, or webhook deliveries without changing the core identity and lifecycle patterns.

Core resources

The control-plane surface

Pools

Namespace, resource family, owner, lifecycle, policy references, regions, and aggregate health.

GET /pools
POST /pools
GET /pools/{pool_id}

Members

Durable member identity, capabilities, readiness, health, capacity, ownership, and extensions.

GET /pools/{id}/members
POST /pools/{id}/members
PATCH /members/{id}

Allocations

Requirements, selected member or route, lease expiry, decision reason, policy version, and state.

POST /allocations
POST /allocations/{id}/commit
POST /allocations/{id}/release

Leases

Time-bounded resource claims with renew, fencing, expiration, and reconciliation semantics.

GET /leases/{id}
POST /leases/{id}/renew
POST /leases/{id}/cancel

Usage events

Observed units, source, related allocation, idempotency, policy or conversion version, and trace.

POST /usage-events
GET /usage-events
POST /reconciliation-runs

Policies

Authorization, filters, ranking, quotas, limits, approval, fallback, retention, and release state.

GET /policies/{id}
POST /policy-versions
POST /policy-aliases/{id}/promote

Common envelope

Make every mutation retry-safe

Recommended request controls

Authorization: scoped identity or short-lived delegated token.
Idempotency-Key: required for value-like or allocation mutations.
If-Match: expected entity version for administrative updates.
Traceparent / correlation ID: propagated through control and data planes.
Request deadline: bounded server work without implying job cancellation.

Pagination and time

Use opaque cursor pagination with stable ordering. Return timestamps in ISO 8601 UTC. Keep occurrence time, server receipt time, and processing time separate for events.

POST /allocations HTTP/1.1
Authorization: Bearer <scoped-token>
Idempotency-Key: 018f...
Content-Type: application/json

{
  "pool_id": "pool_models_global",
  "requirements": {
    "capabilities": ["structured_output"],
    "region": "us"
  },
  "preferences": {
    "latency_class": "interactive"
  },
  "maximum_credits": 120
}

Error contract

Tell clients what they can do next

Differentiate no eligible member, temporary capacity exhaustion, quota rejection, insufficient balance, stale version, invalid transition, dependency failure, and authorization denial. Use stable problem codes and a correlation identifier. Human detail can change; the code and retry guidance should not.

{
  "type": "https://poolapi.com/problems/capacity-exhausted",
  "title": "Eligible capacity is temporarily unavailable",
  "status": 409,
  "code": "capacity_exhausted",
  "retryable": true,
  "retry_after_seconds": 12,
  "correlation_id": "corr_01J..."
}

Specialized modules

Extend without building a super-API

Model routes

Requirements, evaluation suites, adapters, provider extensions, streaming, tools, and fallbacks.

Model pool guide →

Compute jobs

Resource shapes, queue class, image digest, network policy, runtime, events, and outputs.

Compute pool guide →

Asset operations

Canonical asset, amount, account, destination, approvals, signing, settlement, and reconciliation.

Asset pool guide →

Prompt releases

Immutable versions, variables, compatibility, evaluations, aliases, canaries, and rollbacks.

Prompt guide →

Webhook deliveries

Event envelope, endpoint registry, signatures, attempts, retry, replay, and dead-letter state.

Webhook guide →

Governance rounds

Eligibility snapshot, ballots, points, allocation budgets, approvals, tallies, and audit evidence.

Governance guide →