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

# Project

> A project is the workflow container that groups every asset for one piece of work.

## What is a project

A project is the top-level container for everything you do in
Roughy. It groups all the assets that belong to one piece of work —
an episode, an interview, a talk, a launch video. You always create a
project first; uploads and the operations on them happen inside it.

What lives underneath a project:

* **Assets** — the source media you upload. Every asset has a
  `project_id` that points back here.
* **Derived entities** — the [cut](/concepts/cut), subtitle, and
  [renders](/concepts/render) that attach to those assets stay anchored
  under the same project.

## Lifecycle

A project moves through two visible states:

| State      | Meaning                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| `active`   | The default and normal working state. Appears in the active listing.                                         |
| `archived` | Hidden from the active listing but otherwise untouched. Bring back at any time by setting `state: "active"`. |

The shape of the API:

1. **Create** — `POST /v1/projects` with a `name`. Returns the new
   project in `state: "active"`.
2. **List / detail** — `GET /v1/projects` (filterable by `state`),
   `GET /v1/projects/{id}` for one by id.
3. **Rename / archive / unarchive** — `PATCH /v1/projects/{id}`.
   Send `name` to rename, `state: "archived"` to archive,
   `state: "active"` to unarchive.
4. **Delete** — `DELETE /v1/projects/{id}`. Permanently removes the
   project and everything under it (assets and their derived entities),
   including the stored media bytes — immediate and irreversible.

## Listing assets in a project

The asset listing lives on the flat asset surface:
`GET /v1/assets?project_id=<id>` returns the project's assets
newest first. You can scope further with `?state=ready` (or
`pending_upload`); omit `state` and the default returns both —
useful for a UI that wants to show in-flight uploads alongside
finished ones.

Drop the `project_id` filter to list assets across every project
you own. For an asset's full detail or a download URL, call
`GET /v1/assets/{id}` directly with the asset id.

## Naming

`name` is free text. It's the label shown in the dashboard and in
listing responses; it never affects storage paths or URLs. You can
rename a project at any time via `PATCH /v1/projects/{id}` —
existing assets keep working unchanged.

## Related concepts

* [Asset](/concepts/asset) — what lives inside a project.
* [Cut](/concepts/cut) / [Render](/concepts/render) — how to process the assets.
* [Credit ledger](/concepts/credit-ledger) — how assets are billed.