REST API v1

Forge has a basic REST API currently, which we created to enable our CLI tool and to test automated deployments.

Overview

REST API v1 is the original Forge API that provides core functionality for site management, deployments, and data access. This version maintains backward compatibility while offering essential features for integration.

Base URL

All v1 API requests should be made to:

https://api.getforge.com

Authentication

First, you need to login your user (they need to have an existing account from Forge)

Login Endpoint

POST https://api.getforge.com/cli/login

curl -X POST "https://api.getforge.com/cli/login" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d '{
    "email": "YOUR_EMAIL",
    "password": "YOUR_PASSWORD"
}'

Response Example

{"name":"USERNAME","token":"YOUR_TOKEN"}

You'll want to store the token somewhere safe for further requests to the user account.

Available Endpoints

REST API v1 provides the following endpoint categories:

Fetch Sites

You'll probably want to retrieve a list of the Forge users sites at some stage, in order for User to select a site to perform some action.

You can do that like this…

GET https://api.getforge.com/cli/sites

curl -X GET -H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
"https://api.getforge.com/cli/sites?token=YOUR_TOKEN"

Deploy API

POST

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

Request Format

All API requests should include the following headers:

Content-Type: application/json
Cache-Control: no-cache

Authentication Flow

1. Login with email and password to get a token
2. Store the token securely for future requests
3. Include the token as a query parameter in subsequent requests
4. Use the token for site operations and deployments

Error Handling

Error responses include detailed information:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {
      // Additional error details
    }
  }
}

Rate Limits

API v1 implements standard rate limiting:

• 100 requests per minute per API key
• Rate limit headers included in responses
• Exponential backoff recommended for retries

Examples

Complete Authentication Flow

# Step 1: Login to get token
curl -X POST "https://api.getforge.com/cli/login" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d '{
    "email": "your-email@example.com",
    "password": "your-password"
}'

# Step 2: Use token to fetch sites
curl -X GET -H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
"https://api.getforge.com/cli/sites?token=YOUR_TOKEN"

Deploy a Site

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

Use Cases

API v1 is primarily designed for:

• CLI Tool Integration: Enabling the Forge CLI tool
• Automated Deployments: Testing and implementing automated deployment workflows
• Basic Site Management: Fetching site lists and basic operations
• Simple Integrations: Quick scripts and automation tools

Limitations

API v1 has the following limitations:

• Limited endpoint coverage compared to v2
• Basic authentication with account-wide tokens
• No advanced site management features
• No granular access control
• Limited error handling and validation

Migration to v2

While API v1 remains supported, consider migrating to v2 for:

• Enhanced error handling and validation
• Additional endpoints and features
• Improved response structure
• Better documentation and examples
• More secure authentication with scoped tokens

Support

For API v1 support and questions:

• Check the API status page for service updates
• Review rate limit usage in your dashboard
• Contact support for technical issues
• Join the community forums for help