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

# mFoundry Projects API: CRUD Endpoints and Examples

> Create, read, update, and delete mFoundry projects via the REST API. Includes request parameters, response fields, and code examples.

Projects are the top-level organizational unit in mFoundry — they group workflows, tasks, and collaborators together under a shared context. The Projects API lets you automate every stage of a project's lifecycle: provisioning new projects programmatically, polling their status, updating metadata, and tearing them down when they are no longer needed. All project endpoints sit under `/v1/projects`.

***

## GET /v1/projects

List all projects in your organization. Results are returned in reverse-chronological order (newest first) and support cursor-based pagination.

<ParamField query="limit" type="integer">
  Number of projects to return per page. Defaults to `20`. Maximum is `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque pagination cursor returned as `next_cursor` in a previous response. Omit this parameter to start from the first page.
</ParamField>

<ParamField query="status" type="string">
  Filter results by project status. Accepted values: `active`, `archived`, `draft`. Omit to return projects of all statuses.
</ParamField>

**Example response:**

```json theme={null}
{
  "data": [
    {
      "id": "proj_abc123",
      "name": "My Project",
      "status": "active",
      "created_at": "2024-01-15T09:00:00Z"
    }
  ],
  "next_cursor": "cursor_xyz"
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.mfoundry.io/v1/projects?limit=20&status=active" \
    --header "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.mfoundry.io/v1/projects?limit=20&status=active",
    {
      headers: { "Authorization": "Bearer YOUR_API_KEY" },
    }
  );
  const { data, next_cursor } = await response.json();
  ```
</CodeGroup>

***

## POST /v1/projects

Create a new project in your organization. On success, the API returns the newly created project object with a `201 Created` status.

<ParamField body="name" type="string" required>
  The display name for the new project. Must be between 1 and 255 characters.
</ParamField>

<ParamField body="description" type="string">
  An optional human-readable description of the project's purpose. Maximum 1,000 characters.
</ParamField>

<ParamField body="status" type="string">
  Initial status for the project. Accepted values: `active`, `draft`. Defaults to `active`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.mfoundry.io/v1/projects \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "My New Project",
      "description": "Automates our nightly data pipeline.",
      "status": "active"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.mfoundry.io/v1/projects", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "My New Project",
      description: "Automates our nightly data pipeline.",
      status: "active",
    }),
  });
  const project = await response.json();
  ```
</CodeGroup>

**Example response (`201 Created`):**

```json theme={null}
{
  "id": "proj_def456",
  "name": "My New Project",
  "description": "Automates our nightly data pipeline.",
  "status": "active",
  "created_at": "2024-06-10T14:30:00Z",
  "updated_at": "2024-06-10T14:30:00Z"
}
```

***

## GET /v1/projects/:id

Retrieve a single project by its unique ID. Returns the full project object including all metadata fields.

<ParamField path="id" type="string" required>
  The unique identifier of the project (for example, `proj_abc123`).
</ParamField>

**Example response:**

```json theme={null}
{
  "id": "proj_abc123",
  "name": "My Project",
  "description": "Core analytics project.",
  "status": "active",
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-05-22T11:45:00Z"
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.mfoundry.io/v1/projects/proj_abc123 \
    --header "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.mfoundry.io/v1/projects/proj_abc123",
    {
      headers: { "Authorization": "Bearer YOUR_API_KEY" },
    }
  );
  const project = await response.json();
  ```
</CodeGroup>

***

## PUT /v1/projects/:id

Update an existing project's metadata. Supply only the fields you want to change — any field you omit remains unchanged.

<ParamField path="id" type="string" required>
  The unique identifier of the project to update.
</ParamField>

<ParamField body="name" type="string">
  New display name for the project. Must be between 1 and 255 characters.
</ParamField>

<ParamField body="description" type="string">
  Updated description. Pass an empty string to clear the existing description.
</ParamField>

<ParamField body="status" type="string">
  New status for the project. Accepted values: `active`, `archived`, `draft`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
    --url https://api.mfoundry.io/v1/projects/proj_abc123 \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "Renamed Project",
      "status": "archived"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.mfoundry.io/v1/projects/proj_abc123",
    {
      method: "PUT",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Renamed Project",
        status: "archived",
      }),
    }
  );
  const updated = await response.json();
  ```
</CodeGroup>

**Example response:**

```json theme={null}
{
  "id": "proj_abc123",
  "name": "Renamed Project",
  "description": "Core analytics project.",
  "status": "archived",
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-06-11T08:00:00Z"
}
```

***

## DELETE /v1/projects/:id

Permanently delete a project and all of its associated resources. This action cannot be undone and the API returns `204 No Content` with no response body on success.

<ParamField path="id" type="string" required>
  The unique identifier of the project to delete.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.mfoundry.io/v1/projects/proj_abc123 \
    --header "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.mfoundry.io/v1/projects/proj_abc123", {
    method: "DELETE",
    headers: { "Authorization": "Bearer YOUR_API_KEY" },
  });
  // Returns 204 No Content — no response body to parse
  ```
</CodeGroup>

<Warning>
  Deleting a project is **permanent and irreversible**. All workflows, tasks, and configuration associated with the project are immediately destroyed and cannot be recovered. Archive the project (`status: archived`) instead if you want to preserve the data.
</Warning>