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

Documentation Index

Fetch the complete documentation index at: https://docs.deployhub.cloud/llms.txt

Use this file to discover all available pages before exploring further.

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