Skip to main content

​
Endpoint

POST /api/projects/create-with-prompt
Creates a new Polaris project and generates code based on a natural language prompt. This endpoint creates a project, conversation, and immediately starts AI code generation asynchronously.

​
Authentication

Requires a valid Clerk session token. See Authentication for details.

​
Request Body

​
prompt
string
required
Natural language description of what to build.Examples:
  • “Create a React todo app with TypeScript”
  • “Build a REST API with Express and PostgreSQL”
  • “Make a landing page for a SaaS product”

​
Response

​
projectId
string
The Convex ID of the created project. Use this to navigate to the project IDE.

​
Request Example

const response = await fetch('/api/projects/create-with-prompt', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'Create a React todo app with TypeScript and Tailwind CSS'
  })
});

const data = await response.json();
// Navigate to project
window.location.href = `/projects/${data.projectId}`;

​
Response Example

{
  "projectId": "k57abc123def456"
}

​
Project Creation Flow

When you call this endpoint:
1

Project created

A new project is created with a randomly generated name (e.g., “happy-elephant-blue”).
2

Conversation started

A new conversation is created in the project with the title “New Chat”.
3

User message saved

Your prompt is saved as the first user message in the conversation.
4

AI processing begins

An assistant message placeholder is created with status processing, and an Inngest job is triggered.
5

Code generation

The AI agent analyzes your prompt and generates the appropriate files and folder structure.
6

Files created

Generated files are saved to the project and become visible in the file explorer.

​
Project Naming

Projects are automatically named using a random combination of adjective + animal + color:
  • happy-elephant-blue
  • clever-penguin-red
  • swift-dolphin-green
You can rename the project after creation using the project settings.

​
AI Code Generation

The AI uses Claude Opus 4 with access to these tools:
  • createFiles - Generate multiple files
  • createFolder - Create folder structure
  • updateFile - Modify generated files
  • scrapeUrls - Fetch documentation for frameworks/libraries
For best results, be specific about:
  • Framework/language (e.g., “React with TypeScript”)
  • Styling approach (e.g., “Tailwind CSS”)
  • Key features (e.g., “user authentication, dark mode”)

​
Monitoring Progress

After receiving the projectId, navigate to the project IDE to watch the AI generate code in real-time: 
// Navigate to project
window.location.href = `/projects/${projectId}`;
The conversation sidebar will show the AI’s progress as it creates files and folders.

​
Example Prompts

  • “Create a React dashboard with charts and data tables”
  • “Build a Next.js blog with MDX support”
  • “Make a Vue 3 e-commerce product page”
  • “Build a REST API with Express and MongoDB”
  • “Create a GraphQL API with Apollo Server”
  • “Make a FastAPI backend with PostgreSQL”
  • “Create a reusable React modal component with animations”
  • “Build a date picker component with TypeScript”
  • “Make a utility function for API error handling”

​
Learn More

Build docs developers (and LLMs) love

Get started for freeTalk to us