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

# Labs API

> Create, read, update, and delete research labs via the REST API.

# Labs API

Manage research labs programmatically. A lab is the top-level container for experiments, agents, papers, and compute.

## List Labs

<ParamField path="GET" type="/v1/labs">
  Returns all labs the authenticated user has access to.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://www.hubify.com/api/v1/labs \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://www.hubify.com/api/v1/labs", {
    headers: { Authorization: `Bearer ${process.env.HUBIFY_TOKEN}` },
  });
  const { data } = await res.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "lab_abc123",
      "name": "Dark Energy Constraints",
      "slug": "dark-energy",
      "template": "cosmology",
      "visibility": "public",
      "experiment_count": 42,
      "agent_count": 6,
      "created_at": "2026-03-15T08:00:00Z"
    }
  ],
  "meta": { "next_cursor": null, "has_more": false }
}
```

## Get Lab

<ParamField path="GET" type="/v1/labs/:lab_id">
  Returns detailed information about a specific lab.
</ParamField>

<Note>
  This endpoint is planned — not yet shipped. Use `GET /api/v1/labs` (the list endpoint) and filter by `id` or `slug` client-side.
</Note>

<CodeGroup>
  ```bash curl theme={null}
  curl https://www.hubify.com/api/v1/labs/lab_abc123 \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://www.hubify.com/api/v1/labs/lab_abc123", {
    headers: { Authorization: `Bearer ${process.env.HUBIFY_TOKEN}` },
  });
  const { data } = await res.json();
  ```
</CodeGroup>

## Create Lab

<ParamField path="POST" type="/v1/labs">
  Create a new research lab.
</ParamField>

<Note>
  This endpoint is planned. Labs are currently created via the web app or CLI (`hubify lab create`).
</Note>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hubify.com/api/v1/labs \
    -H "Authorization: Bearer $HUBIFY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Dark Energy Constraints",
      "slug": "dark-energy",
      "template": "cosmology",
      "visibility": "public",
      "description": "Constraining dark energy with DESI+Planck"
    }'
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://www.hubify.com/api/v1/labs", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.HUBIFY_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Dark Energy Constraints",
      slug: "dark-energy",
      template: "cosmology",
      visibility: "public",
      description: "Constraining dark energy with DESI+Planck",
    }),
  });
  const { data } = await res.json();
  ```
</CodeGroup>

**Parameters:**

| Field         | Type   | Required | Description                                          |
| ------------- | ------ | -------- | ---------------------------------------------------- |
| `name`        | string | Yes      | Human-readable lab name                              |
| `slug`        | string | No       | URL identifier (auto-generated from name if omitted) |
| `template`    | string | No       | `cosmology`, `ml`, `biology`, `blank`                |
| `visibility`  | string | No       | `public` or `private` (default: `private`)           |
| `description` | string | No       | Brief description                                    |

**Response:** `201 Created`

```json theme={null}
{
  "data": {
    "id": "lab_abc123",
    "name": "Dark Energy Constraints",
    "slug": "dark-energy",
    "site_url": "https://dark-energy.hubify.app",
    "created_at": "2026-04-14T10:00:00Z"
  }
}
```

## Update Lab

<ParamField path="PATCH" type="/v1/labs/:lab_id">
  Update lab settings.
</ParamField>

<Note>
  This endpoint is planned — not yet shipped. Use the web app Settings view to update lab details.
</Note>

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://www.hubify.com/api/v1/labs/lab_abc123 \
    -H "Authorization: Bearer $HUBIFY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Dark Energy & Modified Gravity",
      "visibility": "private"
    }'
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://www.hubify.com/api/v1/labs/lab_abc123", {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.HUBIFY_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Dark Energy & Modified Gravity",
      visibility: "private",
    }),
  });
  ```
</CodeGroup>

All fields are optional. Only provided fields are updated.

## Delete Lab

<ParamField path="DELETE" type="/v1/labs/:lab_id">
  Permanently delete a lab and all its contents.
</ParamField>

<Note>
  This endpoint is planned — not yet shipped. Lab deletion is available in the web app Settings view.
</Note>

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://www.hubify.com/api/v1/labs/lab_abc123 \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript theme={null}
  await fetch("https://www.hubify.com/api/v1/labs/lab_abc123", {
    method: "DELETE",
    headers: { Authorization: `Bearer ${process.env.HUBIFY_TOKEN}` },
  });
  ```
</CodeGroup>

**Response:** `204 No Content`

<Warning>
  This permanently deletes all experiments, papers, agents, knowledge base entries, and the public site. This cannot be undone.
</Warning>