> For the complete documentation index, see [llms.txt](https://robodex.gitbook.io/robodex-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://robodex.gitbook.io/robodex-docs/product-api/product.md).

# API Overview

The product API is a FastAPI app rooted at `apps/api/app.py`.

It mounts routers for:

* ingest,
* design generation,
* exports,
* evolutions,
* workspace projects and threads.

The API owns user workflow orchestration. It does not own the research logic that invents robot bodies, and it does not own the canonical robot IR.

## App factory

`create_app()` in `apps/api/app.py`:

* creates the FastAPI app,
* configures CORS for local and hosted frontend origins,
* initializes demo services,
* mounts product routers,
* exposes health and demo endpoints.

The route layer intentionally composes services rather than embedding all workflow state in the app factory.

## Main route groups

| Route group                           | File                            | Responsibility                                          |
| ------------------------------------- | ------------------------------- | ------------------------------------------------------- |
| `/ingest`                             | `apps/api/routes/ingest.py`     | Analyze task prompts and select motion/video references |
| `/designs`                            | `apps/api/routes/designs.py`    | Generate robot candidates from an ingest job            |
| `/exports` and design artifact routes | `apps/api/routes/exports.py`    | Compile, export, and retrieve design artifacts          |
| `/evolutions`                         | `apps/api/routes/evolutions.py` | Create and run evolution jobs                           |
| `/workspace`                          | `apps/api/routes/workspace.py`  | Project/thread/chat workspace API                       |

## Product candidate model

The API adapts generated robot data into product candidates with fields the frontend can render and discuss:

* candidate id,
* title and rationale,
* embodiment,
* morphology summary,
* torso dimensions,
* limb counts,
* degrees of freedom,
* actuator class,
* sensor list,
* payload and mass estimates,
* confidence,
* compile-safety metadata,
* render payloads,
* grammar HITL payload.

That candidate bundle is not the same as canonical `RobotDesignIR`. It is a product-facing view over generated body information.

## Workspace-first path

The most important user path is:

```
POST /workspace/projects
POST /workspace/projects/{project_id}/threads
POST /workspace/threads/{thread_id}/generate
```

The generation endpoint delegates to `RobotWorkspaceSDK.generate_for_thread()`, which chooses an agent loop, creates a synthetic ingest job, calls the design route, stores artifacts, and appends assistant messages.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://robodex.gitbook.io/robodex-docs/product-api/product.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.