Skip to main content
GET
/
api
/
projects
List User Projects
curl --request GET \
  --url https://api.example.com/api/projects
{
  "success": true,
  "projects": [
    {
      "_id": "<string>",
      "name": "<string>",
      "projectType": "<string>",
      "repoLink": "<string>",
      "status": "<string>",
      "totalRequest": 123,
      "totalBuilds": 123,
      "plan": "<string>",
      "domain": "<string>",
      "createdAt": "<string>",
      "updatedAt": "<string>"
    }
  ],
  "message": "<string>"
}
Retrieves all projects owned by the authenticated user. Returns a formatted list of projects with deployment information, excluding deleted projects.

Authentication

Requires JWT authentication via verifyJWT middleware.

Query Parameters

No query parameters. Returns all non-deleted projects for the authenticated user.

Response

success
boolean
Indicates if the request was successful.
projects
array
Array of project objects sorted by creation date (newest first).

Filtering

The endpoint automatically filters:
  • Projects owned by the authenticated user (via req.user._id)
  • Projects with status not equal to deleted

Sorting

Projects are sorted by createdAt in descending order (newest first).

Selected Fields

For performance, only the following fields are returned:
  • name
  • projectType
  • repoLink
  • status
  • totalRequest
  • plan
  • hascustomDomain
  • customDomain
  • totalBuilds
  • subdomain
  • createdAt
  • updatedAt
Other fields like env, buildCommand, startCommand, etc. are excluded. Use the project details endpoint for complete information.

Error Responses

success
boolean
Always false for errors.
message
string
Error message describing what went wrong.

Common Errors

  • 401 Unauthorized: Missing or invalid JWT token
  • 500 Internal Server Error: "Failed to fetch projects" - Database or server error

Request Examples

cURL

curl -X GET https://api.deployhub.com/api/projects \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JavaScript (Axios)

import axios from 'axios';

const getUserProjects = async () => {
  try {
    const response = await axios.get(
      'https://api.deployhub.com/api/projects',
      {
        headers: {
          'Authorization': `Bearer ${token}`
        }
      }
    );
    
    const { success, projects } = response.data;
    console.log(`Found ${projects.length} projects`);
    
    projects.forEach(project => {
      console.log(`${project.name}: ${project.status} - ${project.domain}`);
    });
    
    return projects;
  } catch (error) {
    console.error('Failed to fetch projects:', error.response.data);
  }
};

JavaScript (Fetch API)

const getUserProjects = async () => {
  const response = await fetch(
    'https://api.deployhub.com/api/projects',
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  const data = await response.json();
  
  if (!data.success) {
    throw new Error(data.message);
  }
  
  return data.projects;
};

TypeScript

interface Project {
  _id: string;
  name: string;
  projectType: 'static' | 'node';
  repoLink: string;
  status: 'pending' | 'building' | 'live' | 'stopped' | 'failed-deploy';
  totalRequest: number;
  totalBuilds: number;
  plan: 'free' | 'pro';
  domain: string;
  createdAt: string;
  updatedAt: string;
}

interface ProjectsResponse {
  success: boolean;
  projects: Project[];
}

const getUserProjects = async (): Promise<Project[]> => {
  const response = await fetch('https://api.deployhub.com/api/projects', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  
  const data: ProjectsResponse = await response.json();
  
  if (!data.success) {
    throw new Error('Failed to fetch projects');
  }
  
  return data.projects;
};

Response Example

Successful Response

{
  "success": true,
  "projects": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "my-react-app",
      "projectType": "static",
      "repoLink": "https://github.com/username/react-app.git",
      "status": "live",
      "totalRequest": 15234,
      "totalBuilds": 12,
      "plan": "free",
      "domain": "my-react-app-a3f9k2.deployhub.online",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:22:00.000Z"
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "name": "express-api",
      "projectType": "node",
      "repoLink": "https://github.com/username/express-server",
      "status": "live",
      "totalRequest": 8921,
      "totalBuilds": 8,
      "plan": "pro",
      "domain": "api.example.com",
      "createdAt": "2024-01-10T08:15:00.000Z",
      "updatedAt": "2024-01-19T11:45:00.000Z"
    },
    {
      "_id": "507f1f77bcf86cd799439013",
      "name": "landing-page",
      "projectType": "static",
      "repoLink": "https://github.com/username/landing-page",
      "status": "building",
      "totalRequest": 0,
      "totalBuilds": 1,
      "plan": "free",
      "domain": "landing-page-x9k2m1.deployhub.online",
      "createdAt": "2024-01-22T16:00:00.000Z",
      "updatedAt": "2024-01-22T16:00:00.000Z"
    },
    {
      "_id": "507f1f77bcf86cd799439014",
      "name": "blog",
      "projectType": "static",
      "repoLink": "https://github.com/username/blog",
      "status": "failed-deploy",
      "totalRequest": 2341,
      "totalBuilds": 5,
      "plan": "free",
      "domain": "blog-p4j8n3.deployhub.online",
      "createdAt": "2024-01-05T12:00:00.000Z",
      "updatedAt": "2024-01-18T09:30:00.000Z"
    }
  ]
}

Empty Projects List

{
  "success": true,
  "projects": []
}

Error Response

{
  "success": false,
  "message": "Failed to fetch projects"
}

Use Cases

Dashboard Display

Display all user projects on a dashboard:
const ProjectsDashboard = () => {
  const [projects, setProjects] = useState([]);
  
  useEffect(() => {
    getUserProjects().then(setProjects);
  }, []);
  
  return (
    <div>
      {projects.map(project => (
        <ProjectCard
          key={project._id}
          name={project.name}
          status={project.status}
          domain={project.domain}
          type={project.projectType}
          builds={project.totalBuilds}
          requests={project.totalRequest}
        />
      ))}
    </div>
  );
};

Filter by Status

const getLiveProjects = async () => {
  const projects = await getUserProjects();
  return projects.filter(p => p.status === 'live');
};

const getFailedProjects = async () => {
  const projects = await getUserProjects();
  return projects.filter(p => p.status === 'failed-deploy');
};

Project Statistics

const getProjectStats = async () => {
  const projects = await getUserProjects();
  
  return {
    total: projects.length,
    live: projects.filter(p => p.status === 'live').length,
    building: projects.filter(p => p.status === 'building').length,
    failed: projects.filter(p => p.status === 'failed-deploy').length,
    totalRequests: projects.reduce((sum, p) => sum + p.totalRequest, 0),
    totalBuilds: projects.reduce((sum, p) => sum + p.totalBuilds, 0),
    proProjects: projects.filter(p => p.plan === 'pro').length
  };
};

Domain Resolution

The domain field intelligently returns:
  • Custom Domain: If hascustomDomain is true and customDomain is set, returns the custom domain
  • DeployHub Subdomain: Otherwise, returns {subdomain}.deployhub.online
This allows you to display the correct accessible URL without additional logic:
const getProjectUrl = (project) => {
  return `https://${project.domain}`;
};

Performance Considerations

  • Uses .lean() for faster queries (returns plain JavaScript objects)
  • Only selects necessary fields to reduce data transfer
  • Indexed on owner and status for fast filtering
  • Sorted by createdAt with index support
  • Create Deployment - Deploy a new project
  • Redeploy Project - Redeploy existing project
  • Get Project Details - Get complete project information including build settings
  • Get Project Builds - View build history for a specific project