Technical Reference

API Overview

Architecture, authentication, and general patterns for the installation API.

Architecture

The API follows REST principles with JSON request/response bodies. All endpoints are versioned and follow semantic URL structure.

Component	Technology	Purpose
Frontend	Astro + React Islands	Static pages with interactive components
API Layer	Astro API Routes	Server-side logic and data access
Data Store	File-based JSON	Simple persistence for configuration
MCP Integration	FastMCP / Model Context Protocol	LLM tool integration

Base URL

 # Development
http://localhost:4321/api

# Production
https://your-domain.com/api 

Authentication

Public endpoints require no authentication. Protected endpoints use bearer token authentication.

Token format

Authorization: Bearer <token>

Example authenticated request

 fetch('/api/share', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-token-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ content: 'example' })
}) 

Token configuration

Set in environment variables:

 .env 
 API_SECRET_KEY=your-secret-key-here 

Request and response format

All requests and responses use JSON format with UTF-8 encoding.

Standard request

 POST /api/endpoint
Content-Type: application/json

{
  "parameter": "value",
  "options": {
    "nested": true
  }
} 

Success response

 HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "data": {
    "id": "abc123",
    "created": "2024-01-16T10:00:00Z"
  }
} 

Error response

 HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Parameter 'content' is required",
    "details": {
      "field": "content",
      "constraint": "required"
    }
  }
} 

HTTP status codes

Standard HTTP status codes indicate request outcome.

Code	Meaning	Usage
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid parameters or malformed request
`401`	Unauthorized	Missing or invalid authentication token
`403`	Forbidden	Valid credentials but insufficient permissions
`404`	Not Found	Resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error

Error handling

All errors follow a consistent structure for programmatic handling.

Field	Type	Description
`success`	boolean	Always `false` for errors
`error.code`	string	Machine-readable error code
`error.message`	string	Human-readable error description
`error.details`	object	Optional additional context

Common error codes

• INVALID_INPUT - Required parameter missing or invalid format
• AUTHENTICATION_FAILED - Invalid or expired token
• RATE_LIMIT_EXCEEDED - Too many requests in time window
• RESOURCE_NOT_FOUND - Requested resource does not exist
• INTERNAL_ERROR - Unexpected server-side error

Client error handling example

 async function callAPI(endpoint, data) {
  try {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });

    const result = await response.json();

    if (!result.success) {
      console.error(`API Error: ${result.error.code}`);
      console.error(`Message: ${result.error.message}`);

      // Handle specific error codes
      switch (result.error.code) {
        case 'RATE_LIMIT_EXCEEDED':
          // Wait and retry
          break;
        case 'AUTHENTICATION_FAILED':
          // Redirect to login
          break;
        default:
          // Show generic error
      }
    }

    return result;
  } catch (err) {
    console.error('Network error:', err);
  }
} 

Rate limiting

API endpoints enforce rate limits to prevent abuse and ensure fair usage.

Endpoint	Limit	Window
Public endpoints	60 requests	per minute
Authenticated endpoints	300 requests	per minute
Share API	30 requests	per minute

Rate limit headers

 X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705401600 

X-RateLimit-Reset value is a Unix timestamp indicating when the limit resets.

Versioning

API versions are specified in the URL path. Breaking changes increment the version number.

 # Current version (v1)
/api/v1/share

# Future versions maintain backward compatibility
/api/v1/share  # Still available
/api/v2/share  # New version with breaking changes 

Deprecation policy

Deprecated API versions remain functional for 12 months after deprecation announcement. Clients receive warnings in response headers during this period.

CORS configuration

Cross-Origin Resource Sharing (CORS) allows API access from web applications on different domains.

Allowed origins

 .env 
 # Set in environment variables
CORS_ORIGINS=https://your-domain.com,https://www.your-domain.com

# Wildcard for development only
CORS_ORIGINS=* 

CORS headers

 Access-Control-Allow-Origin: https://your-domain.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400 