API Overview

Introduction

The Polaris IDE API provides programmatic access to create and manage projects, interact with AI features, and handle file operations. All API endpoints require authentication via Stack Auth JWT tokens.

Base URL

The API is hosted at the same domain as your Polaris IDE instance:

https://your-domain.com/api

For local development:

http://localhost:3000/api

Authentication

All API endpoints require authentication using Stack Auth. See the Authentication page for details on obtaining and using JWT tokens.

Request Format

All POST requests require:

Content-Type: application/json header
Valid JWT token in the Authorization header
JSON request body (where applicable)

Response Format

All responses are returned in JSON format:

{
  "success": true,
  "data": { ... }
}

Or in case of errors:

{
  "error": "Error message",
  "status": 400
}

Error Handling

The API uses standard HTTP status codes:

Status Code	Meaning
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Missing or invalid authentication
`403`	Forbidden - Project limit reached or access denied
`404`	Not Found - Resource doesn’t exist
`409`	Conflict - Resource already being processed
`500`	Internal Server Error

Common Error Responses

{
  "error": "Unauthorized"
}

Rate Limiting

Polaris IDE implements usage-based limits via Autumn (Stripe) integration:

Project Limits

Tier	Projects	Price
Free	10	$0/mo
Pro Monthly	Unlimited	$29/mo
Pro Yearly	Unlimited	$290/yr

AI Features

AI features (suggestions, quick edit, conversations) are available to all users. Rate limiting is handled at the provider level (OpenRouter or Cerebras).

API Endpoints

Projects

POST /api/projects/create - Create a new project
DELETE /api/projects/delete - Delete a project
POST /api/projects/generate - Generate project from AI description
POST /api/projects/check-limit - Check project limit

GitHub Integration

POST /api/github/import - Import repository from GitHub
POST /api/github/export - Export project to GitHub

AI Features

POST /api/messages - Send a conversation message
DELETE /api/messages - Cancel message processing
POST /api/suggestion - Get code suggestion
POST /api/quick-edit - Quick edit with AI

System

GET /api/health - Health check endpoint

Health Check

/api/health

GET

Check API health status

Response

status

string

Always returns “ok” if API is healthy

timestamp

number

Current server timestamp in milliseconds

environment

string

Either “electron” or “web” depending on the runtime

Example Request

cURL

curl https://your-domain.com/api/health

Example Response

{
  "status": "ok",
  "timestamp": 1735660800000,
  "environment": "web"
}

Next Steps

Authentication

Learn how to authenticate API requests

Projects API

Create and manage projects

Messages API

Interact with AI conversations

AI Suggestions

Use AI-powered code features

Overview

Endpoints

Convex Schema

Introduction

Base URL

Authentication

Request Format

Response Format

Error Handling

Common Error Responses

Rate Limiting

Project Limits

AI Features

API Endpoints

Projects

GitHub Integration

AI Features

System

Health Check

Response

Example Request

Example Response

Next Steps

Authentication

Projects API

Messages API

AI Suggestions

Build docs developers (and LLMs) love

Overview

Endpoints

Convex Schema

​Introduction

​Base URL

​Authentication

​Request Format

​Response Format

​Error Handling

​Common Error Responses

​Rate Limiting

​Project Limits

​AI Features

​API Endpoints

​Projects

​GitHub Integration

​AI Features

​System

​Health Check

​Response

​Example Request

​Example Response

​Next Steps

Authentication

Projects API

Messages API

AI Suggestions

Build docs developers (and LLMs) love

Introduction

Base URL

Authentication

Request Format

Response Format

Error Handling

Common Error Responses

Rate Limiting

Project Limits

AI Features

API Endpoints

Projects

GitHub Integration

AI Features

System

Health Check

Response

Example Request

Example Response

Next Steps