Agent API

Quickstart

1. Authenticate

Authenticate with your Wolf You Feed Agent API key, the wyf_pk_… credential issued under Settings → API Access after approval.

Do not send keys issued by any third-party model or infrastructure provider. You are accessing the WYF decision system, not an individual model. WYF manages the complete orchestration for your Decision Opportunity. This API accepts only a WYF-issued Agent key; no third-party provider keys are required.

Send your API key in exactly one header. Either header works; sending both returns 400.

X-API-Key: wyf_pk_REDACTED

or

Authorization: Bearer wyf_pk_REDACTED

NOTE: One API request to WYF can require substantially more inference than a single model call. Keep Agent keys out of source control, client apps, and public repos. You can revoke a key at any time from the same Settings page.

2. Submit a job

Every job submission needs a unique Idempotency-Key. Retrying the same body with the same key is safe and never bills twice.

POST /partner/v1/jobs
X-API-Key: wyf_pk_REDACTED
Idempotency-Key: 6f7e5a6c-1b32-42b8-ae53-0ce2ccb3916c
Content-Type: application/json

{
  "query": "Our founder has six months of runway. Should we hire a senior seller now or preserve cash until two design partners renew?",
  "workflow_mode": "standard",
  "rationale": false
}

Accepted submissions return 202:

{
  "id": "8f14e45f-ceea-467a-9a3f-1b2c7d9e04aa",
  "status": "queued",
  "poll_after_seconds": 10,
  "workflow_mode": "standard",
  "rationale": false,
  "created_at": "2026-08-08T14:02:11Z",
  "updated_at": "2026-08-08T14:02:11Z",
  "completed_at": null,
  "error": null,
  "cost_usd": 0.0,
  "result": null
}

We never echo your query back. Job responses carry no prompt text. You can check the status of your job by polling the API with the job ID.

3. Poll until terminal

GET /partner/v1/jobs/{job_id}
X-API-Key: wyf_pk_REDACTED

Wait at least 10 seconds between polls. Non-terminal responses include poll_after_seconds: 10 and Retry-After: 10. queued and running are non-terminal. succeeded, failed, and dead_letter are terminal; stop polling when you see one.

{
  "id": "8f14e45f-ceea-467a-9a3f-1b2c7d9e04aa",
  "status": "succeeded",
  "poll_after_seconds": null,
  "workflow_mode": "standard",
  "rationale": false,
  "created_at": "2026-08-08T14:02:11Z",
  "updated_at": "2026-08-08T14:03:47Z",
  "completed_at": "2026-08-08T14:03:47Z",
  "error": null,
  "cost_usd": 0.42,
  "result": {
    "decision": "Hold the hire until the first renewal closes, and ...",
    "council_status": "full"
  }
}

Request reference

• Idempotency: Idempotency-Key is required, may contain at most 128 characters, and should normally be a UUID.
• Grants: a missing scope or mode grant returns 403 before anything is queued or billed.

Decision-first quantitative refinement

Quantitative refinement does not turn WYF into a calculator that replaces judgment. WYF still returns the governed Decision. A calculation supplies inspectable evidence: what assumptions were used, what the numbers imply, what remains uncertain, and what would change the result.

What the calculations answer

• Cash-flow runway: Will the current plan cross a stated cash floor, and when?
• Consumable depletion: Which recorded consumable reaches its floor inside the planning horizon?
• Expected Value: Which option has the best probability-weighted result under explicit assumptions?
• Pareto trade-offs: Which choices are clearly dominated, and which still require a human value judgment?
• Evidence updates: How do explicit binary observations or stated likelihoods change a prior?
• Intervals and personal comparisons: What range describes a rate or a measured before-and-after difference?
• Seeded stress tests: How do bounded uncertain inputs change the result, and which input drives it?
• Calibration: Did prior probabilities and intervals perform as declared when outcomes arrived?
• Plans inside hard limits: Which bounded assignment, schedule, or linear allocation is feasible and best under the stated objective?

We partner to accelerate Bayesian search, finite-horizon planning, and system-of-systems composition for sponsored programs. The public calculation catalog is Decision Science. Request shapes for Precompute live in the interactive API reference.

If a typed Precompute payload is missing a required field, WYF returns 422 with detail.code = "quantitative_inputs_incomplete" and a bounded input_requirements list. No Decision work is billed. Complete the listed fields and resubmit.

Response reference

Errors

Two different things return 422.

• Schema validation: fix the field-level errors, then retry.
• Semantic Admission: a declined submission returns the fixed body below and should not be retried unchanged.

{"detail": {"code": "job_not_admitted"}}

Branch on job_not_admitted rather than parsing prose.

Limits

• Request submissions: 10 requests per minute and 60 per hour, per key.
• Polling job completions: 12 requests per minute, per key; the recommended interval is 10 seconds.
• Async / parallel requests: one job in flight per account by default. A second submission returns 429.
• Agent key requests: one pending request per account. A human reviews it and issues a wyf_pk_… key. The form does not mint a JWT or a key. Further submissions while a request is pending are ignored.

Semantic Admission

Every job passes Semantic Admission before it is queued. Admission asks one question: is the primary intent a genuine Decision Opportunity, meaning an identified person or team choosing what to do next when the outcome matters?

A strong Decision Opportunity ideally names the actor, the stakes, the constraints, and at least two potentially actionable options from which a reasonable person could choose, each with consequences attached:

• Hire for my business now vs. preserve cash until contract renewals close
• Move for the job vs. stay for my family and renegotiate remote
• Pay down the card vs. keep the emergency reserve intact

Be specific. Be descriptive. Be verbose. Include details relevant to the choice: names or aliases of the stakeholders, dollar amounts, timelines, calories burned, reps done, etc.

• Not a Decision: bulk generation, summarization, extraction, generic classification, product-help questions better served via Help after you sign in, and attempts to probe system internals return 422 with job_not_admitted. No credit is reserved.
• Admission unavailable: the API returns 503 and creates no job rather than guessing. Retry after a short delay.

Credits

Every registered user who requests introductory Agent API access receives $10 in introductory credits. Add more from Settings → Usage (same Stripe pack as the website) or request an operator grant from Settings → API Access.

What counts as a Decision? A new job (a new idempotency key) is one Decision Session. That session is one Decision, regardless of how many models ran and whether you chose Precompute or Validate. A follow-up job is another Decision. Wolf You Feed is for decisions, not casual chatting.

• Request access in Settings → API Access.
• Website Decisions and Agent API jobs draw on one account balance.
• A hold is placed when a job is accepted and settled to actual cost when it finishes. Rejected and non-admitted submissions cost nothing. If--for whatever reason--the job fails, you will not be charged. If the job was rejected, simply refactor your input and try again.
• Submit an Agent key request. A human reviews it before a key is minted.

Data handling

Agent API traffic is governed by the following controls:

• United States boundary: traffic enters through the United States edge, and durable WYF records remain encrypted in United States storage.
• Governed execution: the same multi-stage Decision pipeline serves the website and the Agent API. Unreviewed execution changes are blocked before a job is admitted.
• Current service scope: encrypted transport and storage, tenant-scoped credentials, isolated records, bounded queues, and account-level deletion protect personal and unregulated Decision work. PHI, CUI, export-controlled, and classified data remain outside the current service scope.
• Deletion: deleting your account purges its Agent keys and every associated job.

Get access

1. Create a Wolf You Feed account and sign in.
2. Open Settings → API Access.
3. Request an Agent key and introductory credits. A short note about your use case is optional and helps us prioritize.
4. When approved, copy the key once and store it in a secrets manager.