Projects API - Polaris IDE

Overview

The Projects API allows you to create, delete, and manage Polaris IDE projects programmatically. Projects are containers for files and conversations.

Create Project

/api/projects/create

POST

Create a new empty project

Request Body

name

string

required

The name of the project

Response

projectId

string

The unique ID of the created project

tracked

boolean

Whether usage was successfully tracked in Autumn

currentUsage

number

Current number of projects created

limit

number

Maximum number of projects allowed (10 for free, unlimited for Pro)

Example Request

cURL

curl -X POST https://your-domain.com/api/projects/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"name": "My New Project"}'

JavaScript

const response = await fetch('/api/projects/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ 
    name: 'My New Project' 
  })
});

const data = await response.json();
console.log(data.projectId);

Example Response

Success

{
  "projectId": "k17a8b9c0d1e2f3g4h5i6j7",
  "tracked": true,
  "currentUsage": 3,
  "limit": 10
}

Limit Reached

{
  "error": "Project limit reached. Please upgrade to Pro for unlimited projects.",
  "currentUsage": 10,
  "limit": 10,
  "allowed": false
}

Error Codes

400 - Missing or invalid project name
401 - Unauthorized (missing/invalid token)
403 - Project limit reached
500 - Server error

Delete Project

/api/projects/delete

DELETE

Delete an existing project and all its files

Query Parameters

projectId

string

required

The ID of the project to delete

Response

success

boolean

Always true on successful deletion

message

string

Confirmation message

Example Request

cURL

curl -X DELETE "https://your-domain.com/api/projects/delete?projectId=k17a8b9c0d1e2f3g4h5i6j7" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JavaScript

const projectId = 'k17a8b9c0d1e2f3g4h5i6j7';

const response = await fetch(`/api/projects/delete?projectId=${projectId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();

Example Response

Success

{
  "success": true,
  "message": "Project deleted and usage updated"
}

Error Codes

400 - Missing project ID
401 - Unauthorized
500 - Server error

Deleting a project is permanent and cannot be undone. All files and conversations will be deleted.

Generate Project

/api/projects/generate

POST

Generate a project from an AI description using background jobs

Request Body

description

string

required

Natural language description of the project to generate (minimum 10 characters)

projectName

string

Optional custom name for the project. Defaults to “Generated Project “

Response

success

boolean

Always true on successful trigger

projectId

string

The ID of the created project

runId

string

The Trigger.dev background job run ID for tracking generation progress

Example Request

cURL

curl -X POST https://your-domain.com/api/projects/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "description": "A React todo app with local storage and dark mode",
    "projectName": "Todo App"
  }'

JavaScript

const response = await fetch('/api/projects/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ 
    description: 'A React todo app with local storage and dark mode',
    projectName: 'Todo App'
  })
});

const { projectId, runId } = await response.json();

Example Response

Success

{
  "success": true,
  "projectId": "k17a8b9c0d1e2f3g4h5i6j7",
  "runId": "run_1234567890abcdef"
}

Error Codes

400 - Invalid description (too short)
401 - Unauthorized
403 - Project limit reached
500 - Server error or billing configuration issue

Project generation runs asynchronously via Trigger.dev. Use the runId to track progress, or monitor the project’s generation events in the UI.

Check Project Limit

/api/projects/check-limit

POST

Check if user can create more projects

Response

allowed

boolean

Whether the user can create more projects

currentUsage

number

Current number of projects

limit

number

Maximum allowed projects (10 for free tier)

fallback

boolean

If true, the check proceeded without Autumn validation (allows creation)

Example Request

cURL

curl -X POST https://your-domain.com/api/projects/check-limit \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JavaScript

const response = await fetch('/api/projects/check-limit', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const { allowed, currentUsage, limit } = await response.json();

Example Response

Allowed

{
  "allowed": true,
  "currentUsage": 5,
  "limit": 10
}

Limit Reached

{
  "allowed": false,
  "error": "Project limit reached. Please upgrade to Pro for unlimited projects.",
  "currentUsage": 10,
  "limit": 10
}

Import from GitHub

/api/github/import

POST

Import a GitHub repository as a new project

Request Body

repoUrl

string

required

Full GitHub repository URL (e.g., https://github.com/owner/repo)

Response

success

boolean

Always true on successful import

projectId

string

The ID of the created project

Example Request

cURL

curl -X POST https://your-domain.com/api/github/import \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"repoUrl": "https://github.com/vercel/next.js"}'

JavaScript

const response = await fetch('/api/github/import', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ 
    repoUrl: 'https://github.com/vercel/next.js'
  })
});

const { projectId } = await response.json();

Example Response

Success

{
  "success": true,
  "projectId": "k17a8b9c0d1e2f3g4h5i6j7"
}

Error Codes

400 - Invalid GitHub URL
401 - Unauthorized
403 - GitHub not connected or project limit reached
500 - Import failed

You must connect your GitHub account in Polaris IDE settings before using import/export features.

Export to GitHub

/api/github/export

POST

Export a project to a GitHub repository

Request Body

projectId

string

required

The ID of the project to export

repoUrl

string

required

Target GitHub repository URL

commitMessage

string

Commit message for the push. Defaults to “Update from Polaris”

createIfNotExists

boolean

Create repository if it doesn’t exist. Defaults to false

isPrivate

boolean

Make new repository private (only used if creating). Defaults to true

repoDescription

string

Description for new repository (only used if creating)

Response

success

boolean

Always true on successful export

Example Request

cURL

curl -X POST https://your-domain.com/api/github/export \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "projectId": "k17a8b9c0d1e2f3g4h5i6j7",
    "repoUrl": "https://github.com/myusername/my-project",
    "commitMessage": "Export from Polaris IDE",
    "createIfNotExists": true,
    "isPrivate": true,
    "repoDescription": "My awesome project from Polaris"
  }'

JavaScript

const response = await fetch('/api/github/export', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ 
    projectId: 'k17a8b9c0d1e2f3g4h5i6j7',
    repoUrl: 'https://github.com/myusername/my-project',
    commitMessage: 'Export from Polaris IDE',
    createIfNotExists: true,
    isPrivate: true,
    repoDescription: 'My awesome project'
  })
});

const { success } = await response.json();

Example Response

Success

{
  "success": true
}

Error Codes

400 - Invalid GitHub URL or missing project ID
401 - Unauthorized
403 - GitHub not connected
404 - Repository doesn’t exist (when createIfNotExists is false)
500 - Export failed or repository creation failed

Export status is tracked on the project. Monitor exportStatus field in the project data to see progress (“exporting”, “completed”, “failed”).

GitHub Connection Status

/api/github/status

GET

Check GitHub OAuth connection status

Response:

connected

boolean

required

Whether user has connected GitHub account

username

string

GitHub username (only if connected)

error

string

Error message if connection invalid

Example:

cURL

curl https://polaris.example.com/api/github/status \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JavaScript

const response = await fetch('/api/github/status', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
const { connected, username } = await response.json();

Usage Tracking

All project operations (create, generate, import) automatically track usage via Autumn (Stripe):

Creating a project: +1 to usage count
Deleting a project: -1 from usage count
Free tier: Limited to 10 projects
Pro tier: Unlimited projects

Next Steps

Files API

Manage files within projects

Messages API

Add AI conversations to projects

Overview

Endpoints

Convex Schema

​Overview

​Create Project

​Request Body

​Response

​Example Request

​Example Response

​Error Codes

​Delete Project

​Query Parameters

​Response

​Example Request

​Example Response

​Error Codes

​Generate Project

​Request Body

​Response

​Example Request

​Example Response

​Error Codes

​Check Project Limit

​Response

​Example Request

​Example Response

​Import from GitHub

​Request Body

​Response

​Example Request

​Example Response

​Error Codes

​Export to GitHub

​Request Body

​Response

​Example Request

​Example Response

​Error Codes

​GitHub Connection Status

​Usage Tracking

​Next Steps

Files API

Messages API

Build docs developers (and LLMs) love

Overview

Create Project

Request Body

Response

Example Request

Example Response

Error Codes

Delete Project

Query Parameters

Response

Example Request

Example Response

Error Codes

Generate Project

Request Body

Response

Example Request

Example Response

Error Codes

Check Project Limit

Response

Example Request

Example Response

Import from GitHub

Request Body

Response

Example Request

Example Response

Error Codes

Export to GitHub

Request Body

Response

Example Request

Example Response

Error Codes

GitHub Connection Status

Usage Tracking

Next Steps