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

# Workspaces and projects

> How Artifacts organizes namespaces, teams, projects, and artifact paths.

Every artifact lives under a two-level namespace: a **workspace** and a **project**.

```text theme={"theme":"github-dark"}
/{workspaceSlug}/{projectSlug}/{artifactSlug}
```

The workspace owns billing, membership, and namespace policy. The project groups related artifacts inside that workspace.

## Workspaces

A workspace is either personal or team-based.

| Kind       | Purpose                              | Created                                                  |
| ---------- | ------------------------------------ | -------------------------------------------------------- |
| `personal` | Your default namespace               | When you claim a username                                |
| `team`     | A shared namespace for collaboration | By signed-in users on a plan that allows team workspaces |

Workspace slugs follow the same rules as usernames:

* 3 to 32 characters.
* Lowercase letters, numbers, underscores, and hyphens.
* Must start and end with a letter or number.
* Must not collide with reserved app routes such as `api`, `docs`, `login`, `dashboard`, or `mcp`.

### Roles

Workspace membership grants access to the projects and artifacts in that namespace.

| Role            | Typical use                                        |
| --------------- | -------------------------------------------------- |
| `owner`         | Full namespace control and billing ownership       |
| `admin`         | Manage members and content                         |
| `member`        | Create and edit content                            |
| `viewer`        | Read visible workspace content                     |
| `billing_admin` | Manage billing without full content administration |

Team invitations can grant `admin`, `member`, `viewer`, or `billing_admin`.

## Projects

A project groups artifacts under a workspace:

```text theme={"theme":"github-dark"}
/alice/default/launch-review
/acme/design-explorations/pricing-grid
```

Each project has a `projectId`, an owner (`ownerUsername` or `workspaceSlug`), a `slug`, a `title`, an optional `description`, and an `icon`. Project slugs normalize to lowercase letters, numbers, and single hyphens.

### Create a project

<CodeGroup>
  ```bash CLI theme={"theme":"github-dark"}
  artifacts project create --json '{"ownerUsername":"alice","slug":"research","title":"Research"}'
  ```

  ```bash REST theme={"theme":"github-dark"}
  curl -X POST "$API_URL/api/workspaces/$WORKSPACE_ID/projects" \
    -H "authorization: Bearer $TOKEN" \
    -H "content-type: application/json" \
    -d '{"slug":"research","title":"Research"}'
  ```
</CodeGroup>

## Resolving paths

Artifacts supports path-first lookup for both humans and agents — useful when you have a URL but need an artifact ID for follow-up calls.

<CodeGroup>
  ```bash CLI theme={"theme":"github-dark"}
  artifacts path project --owner alice --project-slug research
  artifacts path artifact --owner alice --project-slug research --slug synthesis
  ```

  ```text REST theme={"theme":"github-dark"}
  GET /api/by-path/:username
  GET /api/by-path/:username/:projectSlug
  GET /api/by-path/:username/:projectSlug/:slug
  ```
</CodeGroup>

Project path resolution returns the project plus the artifacts visible to the caller. Artifact path resolution applies normal access policy and any share-link grants.