Agents

Power Oracle is designed for direct software use.

The current external contract boundary is /v1.

Agent Integration Checklist

Start with https://api.workcapacity.io/.well-known/api-catalog.
Call GET /v1/movements before constructing compute payloads.
Validate movement names and required inputs before calling POST /v1/compute-power.
Build a canonical session-first, split-aware request.
Store returned workout_id and revision_id for completed workouts.
Use GET /v1/athletes/{athlete_uuid}/workouts to list active canonical workout history.
Use GET /v1/athletes/{athlete_uuid}/workouts/{workout_id} to inspect one past workout before correcting it.
Use GET /v1/athletes/{athlete_uuid}/curve to inspect the bounded power-duration envelope, work-capacity AUC, and domain trends.
Use the revision route to correct completed workouts instead of treating the correction as a new unrelated history item.
Use the void route when the current canonical workout should stop counting and a replacement is not yet known.
Handle 402 Payment Required on the paid compute routes.
Support either x402 or L402 on the paid compute routes.
Read notes so denominator semantics are interpreted correctly.

Minimal Reliable Flow

Read the OpenAPI schema directly.
Inspect GET /v1/movements for supported movement metadata.
Gather workout details without inventing missing timing, loads, or unsupported movements.
Build a canonical POST /v1/compute-power payload with session elapsed time plus ordered splits[].
Call POST /v1/compute-power.
If the request is completed, store the returned workout_id and revision_id.
If the route returns 402, satisfy PAYMENT-REQUIRED or WWW-Authenticate: L402 ..., then retry with the matching proof header.
Interpret results.session, results.splits, results.summary, results.movement_rollups, and notes.
Use the free athlete read routes for history, detail, and curve context after successful completed submissions.

For payment handling, the current production contract is:

POST /v1/compute-power requires payment
POST /v1/workouts/\{workout_id\}/revisions also requires payment
POST /v1/workouts/\{workout_id\}/void is free
GET /v1/athletes/\{athlete_uuid\}/workouts, GET /v1/athletes/\{athlete_uuid\}/workouts/\{workout_id\}, and GET /v1/athletes/\{athlete_uuid\}/curve are free public reads gated by athlete UUID possession
x402 and L402 route pricing are published at GET /v1/payment-requirements
x402 uses USD-denominated exact payment
L402 uses sats derived from the same USD route price with a cached live BTC/USD quote
authorized 2xx and post-billable 4xx responses settle or consume the payment
5xx responses do not settle or consume the payment
if live server behavior differs, treat the live challenge and server behavior as authoritative

Payload Construction Rules

Treat each meaningful work segment as its own split.
Use top-level duration_seconds for session elapsed time.
Use split duration_seconds for split active time only.
If the user only knows one workout-level time, use one split with that duration as active work.
That workout-level time does not define completed rounds or reps. Ask for completed volume if it is still missing.
Put recovery time into rest_seconds_after when it is known.
Do not send server-managed version fields.
Prefer grouped splits over invented per-movement timings when the real data is grouped.
When repeated rounds lack split timing, keep movement order instead of regrouping by movement type.
Treat planned and hypothetical requests as compute-only in MVP. They do not enter stored workout history.

Completed Workout Correction Flow

A successful completed compute creates a stable stored workout.
Persist the returned workout_id and current revision_id.
If you did not store the identifiers locally, list workouts for the athlete and fetch the matching workout detail before deciding on a correction.
If the original completed submission was wrong, call POST /v1/workouts/\{workout_id\}/revisions.
Send the full corrected compute_request, not just a partial diff.
Set supersedes_revision_id to the current canonical revision you are replacing.
If you only know the stored workout is wrong and do not yet know the right replacement, call POST /v1/workouts/\{workout_id\}/void.
Do not keep treating a superseded or voided revision as current truth in your own downstream memory.

History And Curve Reads

Use workout list filters such as since, until, domain, movement, and updated_since to keep sync calls narrow.
Use workout detail reads when the user asks about one specific past workout or before spending a paid revision call.
Use curve reads with bounded max_points; narrow by date range when an analysis does not need lifetime history.
Interpret work_capacity_auc as a Power Oracle work-capacity estimate over the returned curve window, not as a complete claim of total fitness unless the athlete's logs broadly cover time and modal domains.

Failure Handling

Unknown movement: refuse to guess and re-check GET /v1/movements.
Similar or colloquial movement name: refuse to assume equivalence. Do not assume med-ball situp means ab-mat situp.
Missing required input such as external_load: refuse to guess and request the missing value.
Ambiguous timing: preserve only the timing you know and leave the rest as session elapsed time or unattributed duration.
4xx after authorization: treat it as a caller error and remember that it still consumes one paid use.
5xx: surface the failure and retry only with ordinary backoff logic. Current server-error responses do not consume one paid use.
409 on a revision or void request: treat it as a stale-canonical conflict and re-read or re-evaluate before retrying.

Payment Challenge Handling

Rebuild the x402 proof from the current PAYMENT-REQUIRED challenge when the server returns 402.
For L402, pay the challenged invoice and retry with Authorization: L402 <token>:<preimage>.
Do not spend a paid use on invalid payloads if you can prevent that with local validation against the OpenAPI schema and GET /v1/movements.

When An Agent Should Refuse To Guess

A movement name is not in GET /v1/movements.
A required movement input is missing.
The user only knows total session time but asks for fabricated per-movement timing.
The workout description is too incomplete to construct splits without inventing structure.

Operational rule: Power Oracle is designed to be explicit, not magical. A safe agent should validate what the API supports, send only what it knows, and refuse to invent workout structure that was never supplied.

If you need help using Power Oracle, visit Contact or email workcapacity.io@agentmail.to.