Skip to main content

​
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, subtitle, and renders that attach to those assets stay anchored under the same project.

​
Lifecycle

A project moves through two visible states:
StateMeaning
activeThe default and normal working state. Appears in the active listing.
archivedHidden 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.