mFoundry Projects API: CRUD Endpoints and 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.

integer

Number of projects to return per page. Defaults to 20. Maximum is 100.

string

Opaque pagination cursor returned as next_cursor in a previous response. Omit this parameter to start from the first page.

string

Filter results by project status. Accepted values: active, archived, draft. Omit to return projects of all statuses.

Example response:

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

curl --request GET \
  --url "https://api.mfoundry.io/v1/projects?limit=20&status=active" \
  --header "Authorization: Bearer YOUR_API_KEY"

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();

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.

string

required

The display name for the new project. Must be between 1 and 255 characters.

string

An optional human-readable description of the project’s purpose. Maximum 1,000 characters.

string

Initial status for the project. Accepted values: active, draft. Defaults to active.

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"
  }'

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();

Example response (201 Created):

{
  "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.

string

required

The unique identifier of the project (for example, proj_abc123).

Example response:

{
  "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"
}

curl --request GET \
  --url https://api.mfoundry.io/v1/projects/proj_abc123 \
  --header "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://api.mfoundry.io/v1/projects/proj_abc123",
  {
    headers: { "Authorization": "Bearer YOUR_API_KEY" },
  }
);
const project = await response.json();

PUT /v1/projects/:id

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

string

required

The unique identifier of the project to update.

string

New display name for the project. Must be between 1 and 255 characters.

string

Updated description. Pass an empty string to clear the existing description.

string

New status for the project. Accepted values: active, archived, draft.

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"
  }'

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();

Example response:

{
  "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.

string

required

The unique identifier of the project to delete.

curl --request DELETE \
  --url https://api.mfoundry.io/v1/projects/proj_abc123 \
  --header "Authorization: Bearer YOUR_API_KEY"

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

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.

​GET /v1/projects

​POST /v1/projects

​GET /v1/projects/:id

​PUT /v1/projects/:id

​DELETE /v1/projects/:id

GET /v1/projects

POST /v1/projects

GET /v1/projects/:id

PUT /v1/projects/:id

DELETE /v1/projects/:id