Skip to content

API.md

Latest commit

 

History

History
215 lines (167 loc) · 4.48 KB

API.md

File metadata and controls

215 lines (167 loc) · 4.48 KB
Raw

API Documentation

The AiteProfiles application provides a local HTTP API for integration with workflow automation tools like n8n. The API runs only on localhost for security reasons.

Security

  • Localhost Only: API only binds to 127.0.0.1 and ::1
  • Token Authentication: All requests require X-Token header
  • CORS Protection: Only allows specific origins
  • Input Validation: Strict validation of all inputs
  • Error Sanitization: No exception details leaked in responses

Base URL

http://127.0.0.1:28282

Default port is 28282. The actual port may vary if this port is occupied.

Authentication

All API requests require a token in the X-Token header:

X-Token: your-api-token-here

The token is generated on first startup and stored in Windows Credential Manager. If Credential Manager is unavailable, it falls back to a file at %APPDATA%\Codebdbdb\AiteProfiles\api_token.txt.

Endpoints

Health Check

GET /health

Checks if the API server is running.

Response:

{
  "status": "ok"
}

List Profiles

GET /profiles

Returns a list of all detected Chrome profiles.

Response:

[
  {
    "folder": "Default",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "path": "C:\\Users\\John\\AppData\\Local\\Google\\Chrome\\User Data\\Default",
    "passwords": 12,
    "bookmarks": 45,
    "disk_mb": 125.4,
    "last_ts": 1712059200,
    "favorite": true
  },
  {
    "folder": "Profile 1",
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "path": "C:\\Users\\John\\AppData\\Local\\Google\\Chrome\\User Data\\Profile 1",
    "passwords": 8,
    "bookmarks": 22,
    "disk_mb": 67.8,
    "last_ts": 1712058900,
    "favorite": false
  }
]

Open Profile

POST /open_profile

Opens a Chrome profile, optionally with URLs.

Request Body:

{
  "folder": "Default",
  "urls": ["https://example.com", "https://google.com"],
  "incognito": false
}

Parameters:

  • folder: Profile folder name (required if name/email not provided)
  • name: Profile display name (alternative to folder)
  • email: Profile email address (alternative to folder)
  • urls: Array of URLs to open (optional)
  • incognito: Boolean to open in incognito mode (optional, default: false)

Response (Success):

{
  "status": "ok",
  "folder": "Default"
}

Response (Not Found):

{
  "status": "not_found",
  "message": "Profile not found"
}

Compose Email

POST /compose_email

Opens Gmail compose window for a specific profile.

Request Body:

{
  "folder": "Default"
}

Parameters:

  • folder: Profile folder name (required if name/email not provided)
  • name: Profile display name (alternative to folder)
  • email: Profile email address (alternative to folder)

Response (Success):

{
  "status": "ok",
  "folder": "Default"
}

Response (Not Found):

{
  "status": "not_found",
  "message": "Profile not found"
}

HTTP Status Codes

  • 200 OK: Request successful
  • 400 Bad Request: Invalid request or payload
  • 401 Unauthorized: Missing or invalid token
  • 403 Forbidden: Request from non-localhost address
  • 404 Not Found: Endpoint or profile not found
  • 500 Internal Server Error: Unexpected server error

Example Usage

Check API Health

curl -X GET http://127.0.0.1:28282/health \
  -H "X-Token: your-api-token-here"

List Profiles

curl -X GET http://127.0.0.1:28282/profiles \
  -H "X-Token: your-api-token-here"

Open Profile

curl -X POST http://127.0.0.1:28282/open_profile \
  -H "Content-Type: application/json" \
  -H "X-Token: your-api-token-here" \
  -d '{"folder": "Default", "urls": ["https://github.com"]}'

Open Profile in Incognito Mode

curl -X POST http://127.0.0.1:28282/open_profile \
  -H "Content-Type: application/json" \
  -H "X-Token: your-api-token-here" \
  -d '{"folder": "Default", "incognito": true}'

Compose Email

curl -X POST http://127.0.0.1:28282/compose_email \
  -H "Content-Type: application/json" \
  -H "X-Token: your-api-token-here" \
  -d '{"folder": "Default"}'

Rate Limiting

There is no built-in rate limiting. The API is intended for local use with trusted applications.

CORS Policy

The API allows CORS requests from:

  • http://127.0.0.1
  • http://127.0.0.1:28282
  • http://localhost
  • http://localhost:28282

Other origins will receive a restricted CORS policy.

Source of truth

  • src/Api/LocalHttpServer.cs