> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Direct Query API (POST /api/lens/query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT is the base URL https://platform.u1.archetypeai.app with no version path; every endpoint path begins with /api. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# v2.0.x

> These notes detail the new features, enhancements, and fixes included in each release of our platform.

**v2.0.0**

October 28, 2026

## API & Services

* **Files can now be addressed by their `fil_` id:** New endpoints look up a file by its
  TypeID instead of its filename: `GET /api/files/{fil_id}` returns its metadata, `GET
  /api/files/{fil_id}/content` downloads it, and `DELETE /api/files/{fil_id}` deletes it. A
  new `GET /api/files` lists your files. The existing endpoints that look up files by filename
  are still available.
* **File downloads support byte ranges:** Both download endpoints now honor a single `Range:
  bytes=` header (`bytes=a-b`, `bytes=a-` or `bytes=-n`) and answer `206` with
  `Content-Range`. A range that selects no bytes returns `416`, and multi-range or malformed
  headers get the full file with `200`. Downloads now carry `Accept-Ranges: bytes` and a
  strong `ETag`, and `If-Range` is honored so a resumed download can't mix two versions of a
  file.
* **Downloading a file that isn't available yet now returns `409`:** A download of a file that
  is still uploading, corrupt, or has no chunks yet returns `409` instead of `400`. The error
  code stays `file_not_available`.
* **Filenames are limited to 512 characters:** Every upload path now rejects a filename longer
  than 512 characters with `400`. Before, the simple upload paths failed with `500`, and
  direct-upload initiate accepted names up to 1024 characters that could never be stored.
* **New endpoint lists a fine-tuning job's input files:** `GET
  /api/fine-tuning/jobs/{id}/inputs` returns the job's training and validation files, newest
  first, with cursor pagination. Filter with `role` and narrow by `file_id` with a
  case-insensitive `search`.
* **Batch registry lists now use the standard pagination envelope:** `GET
  /api/batch/registry/pipelines`, `GET /api/batch/registry/components` and their
  `/key/{key}/versions` lists now return `{data, has_more, next_cursor, prev_cursor}`. The
  default `limit` is now 100 instead of 50. **Breaking change: the `pipelines` and
  `components` arrays are renamed to `data`, and the `limit` field is no longer returned in
  the body.**
* **The Python client now uses the `/api/<domain>` routes:** The default endpoint is now
  `https://platform.u1.archetypeai.app/api`. **Breaking change: endpoints in the old format,
  such as `https://api.u1.archetypeai.app/v0.5`, no longer work, and the `files_endpoint`,
  `lens_endpoint` and `agent_endpoint` overrides are removed.** The capabilities, sensors,
  messaging, kafka and `files.s3` APIs are removed, and `client.lens` is deprecated with a
  `FutureWarning`.
* **The Python client supports packages:** `client.agents.packages` adds `create`, `list`,
  `get`, `delete` and `wait_until_ready`. `client.agents.instances.create` runs a ready
  package as a batch or serving agent, `wait_until_running` waits for a serving agent to
  start, and `query` sends it a payload. `wait_until_done` now raises an error for a serving
  agent, which never completes.
* **New Python client examples for RED and Anomaly Discovery:**
  `examples/agents/agent_red_lifecycle.py` (pump sensor data) and
  `examples/agents/agent_ad_lifecycle.py` (Tennessee Eastman Process data) each optimize the
  canonical blueprint, promote the best trial, eval it, then bundle and run it.

## Agents

> [!WARNING]
>
> The Bundles endpoints within the Agents API are planned to be removed in the near future. Migrate
> your code to use the new Packages API instead, as soon as possible.

* **Projects group blueprints, evals, optimizations and packages:** The new `/api/projects`
  endpoints create, list, get, update and delete projects. A project is visible to its creator
  and to organization admins, and viewers have read-only access. Blueprints can be registered
  in a project or copied into one with `POST /api/agents/blueprints/{reference}/copy`. Evals,
  optimizations and packages made from a project blueprint land in its project, and their list
  endpoints accept a `project_id` filter. Agent runs inherit the project of the package they
  run, report its `project_id`, and can be filtered by it on `GET /api/agents/instances`. An
  eval, optimization or run in a project may only read input files the project's creator can
  see, and any other input file returns `400`.
* **Packages are the new way to deploy a blueprint:** A package is an immutable build of a
  blueprint that resolves every model slot once. Create and manage packages with `POST
  /api/agents/packages`, `GET /api/agents/packages` and `GET` or `DELETE
  /api/agents/packages/{package_id}`. Run a ready package as a batch or serving agent with
  `POST /api/agents/instances`, and list its runs with the new `package_id` filter on `GET
  /api/agents/instances`.
* **Serving mode is now available to agents:** When starting an agent, you can now specify
  that it should start in `batch` mode (process the inputs then end) or `serving` mode (which
  stays active to answer queries). An agent in `serving` mode lasts as long as the agent
  exists.
* **Anomaly Discovery can be optimized:** The canonical `ad` blueprint's detector is now fit
  by an optimization from normal-only training examples, and `threshold`, `n_neighbors`,
  `metric` and `pca_components` are tunable.
* **RED is fit by optimization and declares its metrics:** The canonical `red` blueprint now
  has a `metrics` section, and its classifier is fit by an optimization instead of shipping
  pre-fit. Optimizations must set its new `events` and `background` values, and its `metric`
  is tunable.
* **New objectives score detection against a background class:** When a category target names
  a `background` label, `foreground_macro_f1`, `detection_recall` and `detection_precision`
  are available as objectives and as the `primary` metric. Binary targets get them too, with
  the non-positive class as the background.
* **Eval and optimization lists can be sorted:** `GET /api/agents/evals` and `GET
  /api/agents/optimizations` take a `sort` of `created_at` (the default), `name` or `score`,
  and an `order` of `asc` or `desc`. Rows with no score sort last. The `after` and `before`
  cursors are now opaque and tied to the sort they came from, and replaying one under a
  different `sort` returns `400`.
* **A blueprint's `source` says how it was derived:** `source` now has a `kind` field:
  `promotion` for a blueprint promoted from an optimization trial, or `copy` for one copied
  into a project. The promotion fields are unchanged.
* **Optimization trials run in parallel:** Trials that don't share encoder settings now run
  across up to eight jobs at once, instead of one after another in a single job.
* **Blueprints can pin a model by its `mdl_` id:** A model slot in a blueprint or bundle can
  now be a model registry `mdl_` id, as well as a registry tag or an `aar_` artifact ref. A
  pinned id keeps resolving after its tags are archived. Canonical blueprints and bundles
  still require tags.
* **Fine-tuned Newton-C LoRA models can be served by id:** A blueprint can name a fine-tuned
  Newton-C model (variants `newton-c-2.5-8b-lora` and `newton-c-2.5-2b-lora`) by its `mdl_` id
  or a tag that points at one. The platform resolves the base model and LoRA adapter and
  merges them at load. Naming a LoRA model in a slot whose node can't apply an adapter returns
  `400`.
* **Optimizations take `targets` overrides and a `seed`:** `targets` overrides work the same
  way they do on eval requests, and the response includes `resolved_targets`. An optional
  non-negative `seed` makes trial sampling reproducible for the same search space.
* **Evals and optimizations can score per-class `precision`, `recall` and `f1`:** These
  objectives take a `class` parameter, for example `{ name: f1_bearing, f1: { class: bearing }
  }`, and can be used as the `primary` metric. An eval's per-target `objectives` override now
  replaces the blueprint's list instead of only narrowing it.
* **Examples can hold several input files, and blueprints can have several targets:** The new
  `per_input` ground-truth form labels each input file of an example. A blueprint is no longer
  limited to one target.
* **Prediction files map each line back to its inputs:** Each line of an eval's predictions
  file now has an `input` field naming the input it came from and a `keys` field with the
  `predicted` and `expected` pairing keys. **The `abstained` field is removed; a prediction
  with no value now has `predicted` set to `null`.**
* **Eval results appear while the eval runs:** Per-example reports are now saved as each
  example completes. Partial results are visible during a run and are kept if the eval fails
  late or is cancelled.
* **One bad example no longer fails a whole eval:** An example whose inputs or ground truth
  can't be read now fails on its own, with a `failed` status and an `error`, and is left out
  of the pooled metrics. The eval fails only if every example fails. In an optimization, a
  failed example still fails its trial.
* **New canonical blueprint, `omega-embeddings`:** It produces Omega embeddings from
  multi-channel numeric time-series data. It runs in batch mode only.

## Console & UI

* **Evals and optimizations have views for detection agents:** The eval and optimization pages
  now show results for Anomaly Discovery and RED agents.
* **Optimization trials open in a side panel:** Selecting a trial opens its results and config
  in a side panel, where you can promote it. The new optimization form also has an optional
  seed field.
* **The fine-tuning job's Training files tab loads from the server:** The tab uses the new
  inputs endpoint for paging, with role and search filters.
* **File Manager asks before deleting a file:** The delete button now opens a confirmation
  dialog.
* **The login page has a new design.**
* **API-key logins show `N/A` as the role:** The sidebar profile no longer shows Viewer for
  every API-key login, because the role isn't available for those sessions.

## Bug Fixes

* **Cancelling an agent run frees its slot right away:** Cancelling a run now also cancels its
  backing job. Before, an orphaned job could keep holding a slot of the organization's
  concurrency limit, so new runs were skipped.
* **A batch run with no source file is refused:** A batch run whose `connectors.source` has no
  `file` ref now returns `400`. Before, it was accepted and stayed `running` for hours.
* **Ground-truth labels for the canonical AD blueprint are no longer refused:** Optimize, eval
  and training jobs refused `constant` and `per_input` labels such as `normal` when a target's
  `labels` held `${values.*}` references, as the canonical AD blueprint's do. These labels are
  now checked after the references are filled in.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.