https://api.beta.hud.ai, every public route under /v2, authenticated with a project
API key. A first call, returning what an agent actually did on a single attempt:
Orientation Authentication · Conventions · Platform modelEndpoint reference Core · Runs and evals · Secondary · Utilities · Secrets · Account · Errors
Authentication
Create a key in Settings → API Keys and send it as a bearer token on every request (see above). Missing or invalid credentials return401. A valid key that may not touch the resource returns
403.
Three kinds of access appear across the surface. An API key is the default; the groups below call
out where an endpoint differs.
Conventions
Every example on this page is generated from the
OpenAPI document, so field names match what the server
sends and receives. The values are placeholders. For a console that sends real requests, use the
interactive reference.
Platform model
Nothing runs until three things exist: a place for an agent to act, something to ask it to do, and a model to do it. The API is organized around those objects.
Environments and builds are the stage, tasksets and tasks are the script, jobs and rollouts are the
action, and traces are the recording. The remaining groups cover credentials, models, live
capacity, and cost.
Endpoint reference
Core
The objects you set up before anything runs: the environment an agent will act in, the suite you grade it on, and the individual tasks inside that suite.Environments
An environment is the sandboxed application an agent works in, packaged as a container image that HUD hosts. The API calls the catalog of those images the registry, and one entry is one environment: its name, its owner, and the work it knows how to run. Reading the registry is how a client discovers what it can run against; creating an entry is what builds do. Each environment declares scenarios, the parameterized task definitions baked into its image. Tasks point at a scenario, which is how a taskset ends up tied to a specific environment.Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Tasksets
A taskset is a named bundle of tasks and the unit an evaluation is defined against: a public benchmark, your team’s regression suite, a customer’s acceptance set. Two jobs are comparable because they ran the same taskset. Three reads answer different questions. Listing discovers the tasksets your team can access. Fetching a taskset returns the card: name, task count, ownership. Exporting returns the tasks themselves, in the same portable shape thatPOST /v2/tasks/upload accepts, which makes export and
upload a round trip you can use to clone a suite, back it up, or sync it into CI.
Set
public_only=true when listing to browse public tasksets across teams. Without it, the list
contains tasksets owned by or shared with your team. Export and by-name lookup require an API key;
fetching a public taskset by ID does not require credentials.Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Tasks
A task is one graded request inside an environment plus the check that decides whether the agent succeeded. Tasks are what a job actually runs. Most of this group exists because tasks are written and reviewed by people before anyone trusts them to grade a model. A task may carry a brief - the prompt and any attachments the idea was captured from - alongside the runnable scenario. Every task carries a status, the review state everyone reads.
While a task is
pending, its taskset can define stages: an optional checklist inside that one
status, such as write, then QA, then polish. A task advances one stage at a time, or jumps back
when someone returns it for more work, and it must reach the last stage before it can become
ready. Tasksets with no stages configured ignore this machinery entirely.
A ready-check evaluates the taskset’s submission requirements against a task: enough graded
traces, accuracy thresholds, particular models, QA checks. It reports each requirement as passed or
failed along with what is missing. It reports; it does not change the status.
Comments and activity are the review trail: human discussion on one side, and an audit
timeline of version and status changes on the other.
Authoring and review state
Request
Response 201
Request
Response 200
Request
Response 200
Request
Response 200
Briefs
These routes are written for the platform UI and accept a browser session, so an API key returns401.
Request
Response 200
Request
200 with a file body.Comments and activity
Request
Response 200
Request
Response 200
Request
Response 200
Request
204 with an empty body.Request
Response 200
Runs and evals
What happens once you actually run something. Rollouts start the work, a job groups it, a trace records each attempt, and an instance is the sandbox an attempt is running in right now.Jobs
A job is one batch of work: this taskset, these models, this many attempts, grouped so the results can be read as a single score. Every graded attempt belongs to a job. There is noPOST /v2/jobs. Jobs come into existence when work is launched, either through
rollouts or when the SDK enters a job as it starts running, and they are cancelled
through rollouts as well. What lives here is everything you do with a job once it exists: read it,
summarize it, page through its attempts, and decide whether its results count.
Single-job reads use optional authentication, so a published job is readable without a key.
Core resource
Request
Response 200
Request
Response 200
Request
Response 200
Aggregates
Rollups over the job’s attempts, so a client does not have to fetch every trace and add the numbers up itself.Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Attempts in the job
Two views of the same attempts. Traces are the full records, suited to scripts. Thumbnails are the compact tiles the platform’s grid renders, with counts per outcome attached.Request
Response 200
Request
Response 200
Request
Response 200
List projections
Shapes built for dashboards: the jobs still running, and job cards with their scores already rolled up so a list of jobs renders in one round trip.Request
Response 200
Request
Response 200
Request
Response 200
State
Publishing makes a job readable without a key. Invalidating marks every attempt in it as not counting toward scores, which is how a run spoiled by a broken environment or a bad prompt is taken out of the record without deleting it.Request
Response 200
Request
Response 200
Request
Response 200
Rollouts
A rollout is one attempt placed on hosted infrastructure: pick up a task, start a sandbox, run the agent, record the result. This group is the go and stop switch for that work, and nothing else. Reading results happens under jobs and traces. Launching returns immediately with ajob_id and a trace_id. The work itself is queued, so a
client polls the trace, or the job, until it finishes.
The three launch endpoints differ in what they are given. Running one task needs a task version and
a model. A batch takes lists of both and groups the result into a single job. Submitting is the
path the SDK uses when it has already minted its own identifiers and describes the work by
environment and task name instead.
Launch
Request
Response 201
Request
Response 201
Request
Response 201
Cancel
Cancelling is scoped: one attempt, one job, or everything you have running.Request
Response 200
Request
Response 200
Request
Response 200
Traces
A trace is one attempt at one task: what the agent saw, every tool call it made, what the environment said back, how long it took, what it cost, and the reward it ended with. Traces are the evidence behind every score on the platform. The record itself is small. The interesting read is events, a flat and typed projection of the attempt’s telemetry into messages, tool calls, and results, ordered by a sequence number. Passing the lastlatest_seq you saw as since_seq returns only what is new, which is how a viewer
follows a run that is still going.
Most reads use optional authentication, so a trace inside a published job is readable without a
key. Writes and the analysis bundle require a key or a session.
Core resource
Request
Response 200
Request
Response 200
Request
Response 200
Telemetry and logs
Three levels of detail: the projected trajectory, the runner’s own logs, and the raw output of the environment container. The analysis bundle packages all of it for an agent that has been asked why a run failed.Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Related traces and validity
Request
Response 200
Request
Response 200
Instances
An instance is a sandbox that is live right now, running one attempt of one environment. Each one holds real compute, so instances are the surface you reach for when a run has hung, when something is stuck holding capacity, or when you want to see what is currently occupied.Request
Response 200
Request
Response 200
Secondary
Two supporting catalogs behind the core loop: how an environment image gets made, and which models you can point at it.Builds
A build turns environment source into the container image that runs attempts. The shape of it is the same as shipping any image: ask where to put the source, upload it, start the build, watch it, then decide whether the result becomes the version new runs use. Uploading is a two-step handshake. Requesting an upload URL returns abuild_id and a one-time
link; your client sends the source archive to that link directly, then triggers the build by ID.
Marking a build as latest is a separate call, which leaves earlier builds in place to roll back to.
Lifecycle
Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Source and workspace
After a build indexes its context, its files can be browsed: the source that was uploaded, and the workspace the build produced. The platform uses this to answer “what did we actually ship in this image?” without a rebuild.Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Request
200 with a file body.Deprecated
Production discovers an image’s scenarios automatically when the build finishes. This route runs
the image on the calling host instead, and exists only for local debugging.
Request
Response 200
Models
A model is an entry in the catalog you point evaluations at. Two kinds share the resource: base models the platform provides, and trainable models your team owns. A team model is created by forking a trainable base, which gives it its own line of checkpoints, one of which is the head that inference uses. Names are resolved rather than guessed: pass whatever model string you have, such as a slug from a config file, and resolve turns it into a catalog record with an ID. Results are the other end of the loop, reporting how the model scored on the tasksets it has been run against.Catalog
Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Training lineage
Request
Response 200
Request
Response 200
Request
Response 200
Request
Response 200
Results and usage
Request
Response 200
Request
Response 200
Request
Response 200
Utilities
Shared plumbing that other groups depend on rather than a resource of its own.Uploads
Some task content is a file rather than text: a spreadsheet the agent must edit, a screenshot, a reference document. Uploading stages that file against a taskset and returns astorage://
locator, which is what a brief or a task definition then refers to.
Both routes accept a browser session, so an API key returns
401.Request
Response 200
Request
Response 200
Secrets
Hosted runs frequently need credentials: the site the environment drives wants a login, the agent wants a provider key. Two stores cover that, and they differ in who owns the value.
At launch both are merged into the run’s environment, and an environment variable wins if the same
name exists in both.
Environment variables
Variables are attached to an environment and injected whenever it runs. A run that needs a credential which is not set will usually fail or refuse to start, so the check endpoint exists to answer “is this environment ready?” before anyone launches anything.Request
Response 200
Request
Response 201
Request
Response 200
Request
204 with an empty body.Request
Response 200
Request
Response 200
Member secrets
Member secrets are yours alone. Beyond ordinary secrets, they carry bring your own key: bind a secret to a model provider and inference you start is billed to your account with that provider instead of the platform’s. Binding is explicit, and one key is bound per provider; a secret that merely has the right name is not used. The key is never sent in a request header, since the platform resolves it server side when the call is made.Request
Response 200
Request
Response 201
Request
Response 200
Request
204 with an empty body.Account
What a run costs, and what stops it from costing more.Limits
A limit is a spending ceiling in US dollars over a week or a month, attached either to a single API key or to one member across all of their keys. A limit set to alert sends mail when it is passed; a limit set to block refuses new work instead. Listing limits also returns the current period’s spend, which is what makes it useful as a read even when nothing is near the ceiling. Scope and interval are fixed once a limit exists, so changing them means deleting the limit and creating a new one. There is no fetch-one route; listing is the read path.Request
Response 200
Request
Response 201
Request
Response 200
Request
204 with an empty body.Completions
One chat completion, proxied through the platform’s inference gateway and billed like any other inference. No environment, no task, no grading: messages in, text out.Request
Response 200
Usage
Spend has two sources: the sandboxes you run, charged by the time they are alive, and the model calls made inside them, charged by tokens. Both are readable as history. Inference is reported at two grains, and the paths are easy to confuse. Bucketed aggregates for charts live at/v2/usage/inference. The row-level log of individual calls lives at
/v2/inference/usage.
Request
Response 200
Request
Response 200
Request
Response 200
Errors
Failures share one envelope, with a machine-readable code and a human-readable message. The status tells you whether to fix the request, the credentials, or the state.
For how the objects fit together beyond the API, see the
platform introduction. For a console that sends real requests, use the
interactive reference.