API

Reach and use the you-agent-factory local HTTP API: how to get a listener running at all, the default base URL, the session-oriented flow, and the path to the operations catalog.

How To Reach

The API binds the loopback interface on the machine that started it, so clients on that machine reach it and nothing else does. The default base URL is http://localhost:7437 unless the process that bound the listener overrode host or port through the global server flag. Point HTTP clients at a factory server you run yourself, never at a documentation host.

Default local base URL

http://localhost:7437

An ordinary run starts no HTTP listener. Batch, continuous, named, portable, replay, mock-worker, and JavaScript runs all execute without one, so a client pointed at the base URL during such a run gets a connection failure — the factory is working, it just is not serving.

Three ways to get a listener

you server
you run --named @you/goal --with-server "Ship the login bugfix"
you run --named @you/goal --with-site "Ship the login bugfix"

Serving the current factory runs until you cancel it. The two run flags serve only for the lifetime of that one run: adding a server keeps the API available without a browser, and adding the site implies that server and opens the embedded dashboard once after readiness. Server-enabled runs bind the loopback host and preferred port, advance past collisions monotonically, and report the URL they actually bound.

Typical Session Flow

The live Factory Session is the unit you discover, inspect, and address. Every session-scoped operation takes a session id in the path, so the first call is always the one that gets you an id.

List sessions to get an id

curl -s "http://localhost:7437/factory-sessions"

Listing sessions is the primary liveness check. An empty list means the host responded but no live session is registered yet. A connection failure means nothing is listening on that host and port at all.

Inspect one session and read its runtime status

curl -s "http://localhost:7437/factory-sessions/<session-id>"
curl -s "http://localhost:7437/factory-sessions/<session-id>/status"

Replace the placeholder with a session id from the list. CLI commands that omit an explicit session target the default compatibility session, but an HTTP client has to name one, so read the id rather than assuming it.

The same two reads from the CLI

you session list
you session show <session-id>

Submitting And Reading Results

Work goes in through the session work endpoint, and finished output comes back through separate result reads: one for the primary result, one for the full result set, and one for a partial result while the session is still running. Durable sessions can also be started directly with synchronous or asynchronous start operations.Prefer a result read over scraping the event stream when you only want the answer. Prefer the event stream when you need ordered progress while the work is still moving.

Submitting work

Streaming Events

Two server-sent event streams are published per session. The canonical stream carries ordered FactoryEvent records and is the one to consume for durable progress. The ephemeral stream carries FactoryResponseEvent records for one invocation's response lifecycle.

Events Reference — the full event corpus and stream contracts

Validating Without A Session

A factory definition can be checked before any session exists. The validation operation takes a definition payload and returns whether it satisfies the factory contract, and a separate preview operation returns the resolved shape a definition would load as.

you factory config validate ./factory/factory.json

The CLI validation command runs through the same validate-only factory contract as the HTTP validation operation, so a definition that passes locally passes over HTTP. Use the CLI while authoring and the endpoint when a service is doing the checking.

Trust Boundaries

Treat the default local bind as an operator-accessible local surface, not a multi-tenant public product edge. The Security and Trust Boundaries page carries local-bind expectations, operator versus autonomous-agent ingress paths, and sensitive artifact handling.Autonomous agents submit work only through the CLI. Dashboard submit and the session work endpoint remain operator paths — do not treat them as a parallel agent control ingress.

Security / Trust Boundaries

How To Use

Start a server, confirm a live session, then call session-scoped status, event, submit, or result operations against that session id. Open the API reference when you need exact paths, methods, media types, or schema components.Exact path, method, media-type, and schema contracts live on the API reference, which renders the shipped OpenAPI document itself rather than a retyped summary of it.

Limits And Assumptions

Coverage here is how to interact with the local HTTP API: getting a listener, the default base URL, the session-oriented flow, and the trust-boundary pointer. It is not the operations catalog, not a live request playground, and not a pasted OpenAPI document. Autonomous agents submit work through the CLI; dashboard submit and operator HTTP submit remain operator surfaces.

API