REST API v2

We've been working on a new and updated API for Forge. This will ultimately replace the current v1 API, though for the time being, they will run side by side.

The goal of the v2 API was to really expose all the Forge features via a suite of endpoints, so you can freely experiment and build workflows that suit you.

Overview & Authentication

The first and most significant change is the API authorisation system. In v1, you had complete access to all of your Forge sites using the given access token. This was like a skeleton key to your entire Forge account, making it very difficult to share with your team or collaborators. In v2, we still have the account-wide token, but we've also introduced a Site token, scoping access to a specific site.

You can find your Account Token in https://getforge.com/#/account/settings and your Site Token in https://getforge.com/#/[site_id]/settings of the Forge Admin panel.

Base URL

All v2 API requests should be made to:

https://api.getforge.com/v2

Request Format

All API requests should include the following headers:

Content-Type: application/json
Accept: application/json

For authentication, use either:

• Account Token: Pass as account_token parameter or in request body
• Site Token: Pass as site_token parameter or in request body

CLI Endpoints

Deploy API

POST

• Endpoint: https://api.getforge.com/v2/cli/deploy
• Description: to deploy your Forge site and create a new version
• Parameters: site_tokens (string), archive (.zip file as multi-part form data)

Versions Info API

POST

• Endpoint: https://api.getforge.com/v2/cli/versions_info
• Description: to retrieve version information for a site
• Parameters: site_tokens (string)

Site Management

Get Site Token

POST

• Endpoint: https://api.getforge.com/v2/account/get_site_token
• Description: to retrieve a site token using account token
• Parameters: account_token (string), site_id (string)

Site Details API

GET

• Endpoint: https://api.getforge.com/v2/settings/site_info
• Description: to retrieve information about one of your Forge sites
• Parameters: site_token (string)

Site Settings API

SSL Mode

POST

• Endpoint: https://api.getforge.com/v2/settings/ssl_mode
• Description: to enable or disable ssl_enabled
• Parameters: site_token (string), status (boolean)

Force SSL Mode

POST

• Endpoint: https://api.getforge.com/v2/settings/force_ssl_mode
• Description: to enable or disable force_ssl_enabled (only valid if ssl_enabled == true)
• Parameters: site_token (string), status (boolean)

TurboJS Mode

POST

• Endpoint: https://api.getforge.com/v2/settings/turbojs_mode
• Description: to enable or disable Turbojs
• Parameters: site_token (string), status (boolean)

Hammer Mode

POST

• Endpoint: https://api.getforge.com/v2/settings/hammer_mode
• Description: to enable or disable Hammer Cloud service
• Parameters: site_token (string), status (boolean)

Compiler Mode

GET/POST

• Endpoint: https://api.getforge.com/v2/settings/compiler_mode
• Description: to get or set compiler mode settings
• Parameters: site_token (string), mode (string)

Domain Name

POST

• Endpoint: https://api.getforge.com/v2/settings/domain_name
• Description: to change the site name. Custom domains are only valid with a paid Forge subscription
• Parameters: site_token (string), new_domain (string)

Deployment Method

POST

• Endpoint: https://api.getforge.com/v2/settings/deployment_method
• Description: to change the deployment method
• Parameters:

For Dropbox:

• site_token (string)
• deployment_method (string e.g. 'dropbox')
• folder_path (string. Relative to dropbox root folder, e.g. '/your_folder_in_root')

Note: Dropbox must already be connected to your Forge Account.

For Github:

• site_token (string)
• deployment_method (string e.g. 'github')
• folder_path (string. Repository folder path)
• branch (string e.g master)

Note: Github must already be connected to your Forge Account.

For Drag & Drop:

• site_token (string)
• deployment_method (string e.g. 'manually')

Deployment Errors

POST

• Endpoint: https://api.getforge.com/v2/settings/deployment_errors
• Description: to retrieve deployment error information
• Parameters: site_token (string)

Site Bandwidth API

GET

• Endpoint: https://api.getforge.com/v2/site_bandwidths
• Description: to retrieve information about one of your Forge sites
• Parameters:
• site_token (string)
• unit (string e.g. 'last month', 'month', 'week', 'last week')
• to (date e.g '2017-01-01')
• after (date e.g. '2015-01-01')

Account Management

Account Plan API

Read Account Plan

GET

• Endpoint: https://api.getforge.com/v2/account/subscription_plan
• Description: to read the current Account Plan
• Parameters: account_token (string)

Change Account Plan

POST

• Endpoint: https://api.getforge.com/v2/account/subscription_plan
• Description: to change the Account Plan
• Parameters: account_token (string), new_plan (string)

Technical Constraints

File Upload Limits

• Deployment files: 2GB maximum (ZIP format only)
• Images: 25MB maximum
• Form files: 10MB maximum

SSL Requirements

• All API calls must use HTTPS
• Base URL: https://api.getforge.com/v2

Date Formats

• All dates must use YYYY-MM-DD format
• Example: 2024-01-15

Error Handling

API v2 uses standard HTTP status codes:

• 200: Success
• 401: Unauthorized (invalid token)
• 404: Not Found
• 422: Validation Error
• 500: Server Error

Error responses follow this format:

{
  "success": false,
  "message": "error description"
}

Examples

Get Site Token from Account

curl -X POST "https://api.getforge.com/v2/account/get_site_token" \
  -H "Content-Type: application/json" \
  -d '{
    "account_token": "YOUR_ACCOUNT_TOKEN",
    "site_id": "your-site-id"
  }'

Deploy a Site

curl -X POST "https://api.getforge.com/v2/cli/deploy" \
  -F "site_tokens=YOUR_SITE_TOKEN" \
  -F "archive=@your-site.zip"

Get Versions Info

curl -X POST "https://api.getforge.com/v2/cli/versions_info" \
  -H "Content-Type: application/json" \
  -d '{
    "site_tokens": "YOUR_SITE_TOKEN"
  }'

Get Site Information

curl -X GET "https://api.getforge.com/v2/settings/site_info?site_token=YOUR_SITE_TOKEN" \
  -H "Accept: application/json"

Configure Compiler Mode

curl -X POST "https://api.getforge.com/v2/settings/compiler_mode" \
  -H "Content-Type: application/json" \
  -d '{
    "site_token": "YOUR_SITE_TOKEN",
    "mode": "jekyll"
  }'

Enable SSL for a Site

curl -X POST "https://api.getforge.com/v2/settings/ssl_mode" \
  -H "Content-Type: application/json" \
  -d '{
    "site_token": "YOUR_SITE_TOKEN",
    "status": true
  }'

Change Deployment Method to GitHub

curl -X POST "https://api.getforge.com/v2/settings/deployment_method" \
  -H "Content-Type: application/json" \
  -d '{
    "site_token": "YOUR_SITE_TOKEN",
    "deployment_method": "github",
    "folder_path": "/",
    "branch": "main"
  }'

Handle Deployment Errors

curl -X POST "https://api.getforge.com/v2/settings/deployment_errors" \
  -H "Content-Type: application/json" \
  -d '{
    "site_token": "YOUR_SITE_TOKEN"
  }'

Get Site Bandwidth

curl -X GET "https://api.getforge.com/v2/site_bandwidths?site_token=YOUR_SITE_TOKEN&unit=month" \
  -H "Accept: application/json"

Read Account Plan

curl -X GET "https://api.getforge.com/v2/account/subscription_plan?account_token=YOUR_ACCOUNT_TOKEN" \
  -H "Accept: application/json"

Key Differences from v1

• Scoped Access: Site tokens provide access to specific sites only
• Enhanced Settings: More granular control over site configuration
• Bandwidth Monitoring: Built-in bandwidth tracking and reporting
• Account Management: Direct access to account plan information
• Improved Security: Better token management and access control
• Compiler Support: Direct control over compiler modes
• Error Handling: Enhanced deployment error reporting

Migration from v1

To migrate from API v1 to v2:

1. Update your base URL to https://api.getforge.com/v2
2. Obtain site-specific tokens for scoped access
3. Update your authentication headers
4. Test your integration with the new endpoints
5. Review the enhanced error handling
6. Update parameter names (e.g., site_token vs site_tokens)

Support

For API v2 support and questions:

• Check the API documentation for endpoint details
• Review the authentication guide for token management
• Test endpoints using the provided examples
• Contact support for technical issues
• Join the developer community for discussions