Introduction

The Forge API allows you to create and interact with servers and sites on Laravel Forge through a simple REST API.

Authentication

In order to use the API, you should authenticate your request by including your API key as a bearer token value:

Authorization: Bearer API_KEY_HERE

Headers

Make sure you have the following content type headers are set on every request:

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

URI

Forge API is hosted on the following base URI:

https://forge.laravel.com/api/v1

Errors

Forge uses conventional HTTP response codes to indicate the success or failure of an API request. The table below contains a summary of the typical response codes:

Code Description 200 Everything is ok. 400 Valid data was given but the request has failed. 401 No valid API Key was given. 404 The request resource could not be found. 422 The payload has missing required parameters or invalid data was given. 429 Too many attempts. 500 Request failed due to an internal error in Forge. 503 Forge is offline for maintenance.

User

show

Response

HTTP Request

GET /api/v1/user

Servers

Create Server

Payload

{ "provider": "ocean2", "credential_id": 1, "name": "test-via-api", "size": "512MB", "database": "test123", "php_version": "php71", "region": "ams2", "recipe_id": null }

Response

{ "server": { "id": 16, "credential_id": 1, "name": "test-via-api", "size": "01", "region": "ams2", "php_version": "php71", "ip_address": null, "private_ip_address": null, "blackfire_status": null, "papertrail_status": null, "revoked": false, "created_at": "2016-12-15 15:04:05", "is_ready": false, "network": [] }, "sudo_password": "baracoda", "database_password": "spotted_eagle_ray" }

HTTP Request

POST /api/v1/servers

Parameters

Key Description provider The server provider. Valid values are ocean2 for Digital Ocean, linode , vultr , aws , hetzner and custom . credential_id This is only required when the provider is not custom . region The name of the region where the server will be created. This value is not required you are building a Custom VPS server. Valid region identifiers. ip_address The IP Address of the server. Only required when the provider is custom . private_ip_address The Private IP Address of the server. Only required when the provider is custom . php_version Valid values are php74 , php73 , php72 , php71 , php70 , and php56 . database The name of the database Forge should create when building the server. If omitted, forge will be used. maria Indicates if MariaDB should be installed. Otherwise, MySQL will be installed. database_type Valid values are mysql , mysql8 , mariadb , postgres . node_balancer Determines if the server should be provisioned as a load balancer. network An array of server IDs that the server should be able to connect to. recipe_id An optional ID of a recipe to run after provisioning. aws_vpc_id ID of the existing VPC aws_subnet_id ID of the existing subnet aws_vpc_name When creating a new one

Server Status

Servers take about 10 minutes to provision. Once the server is ready to be used, the is_ready parameter on the server will be true . You should not repeatedly ping the Forge API asking if the server is ready. Instead, consider pinging the endpoint once every 2 minutes.

Valid Sizes

Check the Regions endpoint for the available sizes and regions IDs.

Custom VPS

While creating a custom VPS, the response of this endpoint will contain a provision_command attribute:

{ "provision_command": "wget -O forge.sh https://..." }

List Servers

Response

{ "servers": [ { "id": 1, "credential_id": 1, "name": "test-via-api", "size": "512MB", "region": "Amsterdam 2", "php_version": "php71", "ip_address": "37.139.3.148", "private_ip_address": "10.129.3.252", "blackfire_status": null, "papertrail_status": null, "revoked": false, "created_at": "2016-12-15 18:38:18", "is_ready": true, "network": [] } ] }

HTTP Request

GET /api/v1/servers

Get Server

Response

{ "server": { "id": 1, "credential_id": 1, "name": "test-via-api", "size": "512MB", "region": "Amsterdam 2", "php_version": "php71", "ip_address": "37.139.3.148", "private_ip_address": "10.129.3.252", "blackfire_status": null, "papertrail_status": null, "revoked": false, "created_at": "2016-12-15 18:38:18", "is_ready": true, "network": [] } }

HTTP Request

GET /api/v1/servers/{id}

Update Server

Payload

{ "name": "renamed-server", "size": "512MB", "ip_address": "192.241.143.108", "private_ip_address": "10.136.8.40", "max_upload_size": 123, "network": [2, 3] }

Response

{ "server": { "id": 16, "credential_id": 1, "name": "test-via-api", "size": "512MB", "region": "Amsterdam 2", "php_version": "php71", "ip_address": null, "private_ip_address": null, "blackfire_status": null, "papertrail_status": null, "revoked": false, "created_at": "2016-12-15 15:04:05", "is_ready": false, "network": [2, 3] } }

HTTP Request

PUT /api/v1/servers/{id}

Update Database Password

Payload

{ "password": "maeve" }

HTTP Request

PUT /api/v1/servers/{serverId}/database-password

This endpoint will update Forge's copy of the primary database password which should be used to authenticate the creation of new databases and database users. This is typically only needed if you are working with a Forge server that was built before database administration was added to Forge.

Delete Server

HTTP Request

DELETE /api/v1/servers/{id}

Reboot Server

HTTP Request

POST /api/v1/servers/{id}/reboot

Revoke Forge access to server

HTTP Request

POST /api/v1/servers/{id}/revoke

Reconnect revoked server

Response

{ "public_key": "CONTENT_OF_THE_PUBLIC_KEY" }

HTTP Request

POST /api/v1/servers/{id}/reconnect

This endpoint will return an SSH key which you will need to add to the server. Once the key has been added to the server, you may "reactivate" it.

Reactivate revoked server

HTTP Request

POST /api/v1/servers/{id}/reactivate

Get Recent Events

Response

[ { "server_id": 18, "ran_as": "forge", "server_name": "billowing-cliff", "description": "Deploying PHP Info Page.", "created_at": "2017-04-28 18:08:44" } ]

HTTP Request

GET /api/v1/servers/events

Parameters

Key Description server_id Optionally specify a server_id to get recent events of only this server.

Services

Start Service

HTTP Request

POST /api/v1/servers/{id}/services/start

Payload

{ "service": "service-name" }

Stop Service

HTTP Request

POST /api/v1/servers/{id}/services/stop

Payload

{ "service": "service-name" }

Restart Service

HTTP Request

POST /api/v1/servers/{id}/services/restart

Payload

{ "service": "service-name" }

Reboot MySQL

HTTP Request

POST /api/v1/servers/{id}/mysql/reboot

Stop MySQL

HTTP Request

POST /api/v1/servers/{id}/mysql/stop

Reboot Nginx

HTTP Request

POST /api/v1/servers/{id}/nginx/reboot

Stop Nginx

HTTP Request

POST /api/v1/servers/{id}/nginx/stop

Reboot Postgres

HTTP Request

POST /api/v1/servers/{id}/postgres/reboot

Stop Postgres

HTTP Request

POST /api/v1/servers/{id}/postgres/stop

Reboot PHP

Payload

{ "version": "php74" }

HTTP Request

POST /api/v1/servers/{id}/php/reboot

Install Blackfire

Payload

{ "server_id": "...", "server_token": "..." }

HTTP Request

POST /api/v1/servers/{id}/blackfire/install

Remove Blackfire

HTTP Request

DELETE /api/v1/servers/{id}/blackfire/remove

Install Papertrail

Payload

{ "host": "192.241.143.108" }

HTTP Request

POST /api/v1/servers/{id}/papertrail/install

Remove Papertrail

HTTP Request

DELETE /api/v1/servers/{id}/papertrail/remove

Daemons

Create Daemon

Payload

{ "command": "COMMAND", "user": "root", "directory": "/home/forge/foo.com" }

Response

{ "daemon": { "id": 1, "command": "COMMAND", "user": "root", "directory": "/home/forge/foo.com", "status": "installing", "created_at": "2016-12-16 15:46:22" } }

HTTP Request

POST /api/v1/servers/{serverId}/daemons

List Daemons

Response

{ "daemons": [ { "id": 1, "command": "COMMAND", "user": "root", "directory": "/home/forge/foo.com", "status": "installing", "created_at": "2016-12-16 15:46:22" } ] }

HTTP Request

GET /api/v1/servers/{serverId}/daemons

Get Daemon

Response

{ "daemon": { "id": 1, "command": "COMMAND", "user": "root", "directory": "/home/forge/foo.com", "status": "installing", "created_at": "2016-12-16 15:46:22" } }

HTTP Request

GET /api/v1/servers/{serverId}/daemons/{daemonId}

Delete Daemon

HTTP Request

DELETE /api/v1/servers/{serverId}/daemons/{daemonId}

Restart Daemon

HTTP Request

POST /api/v1/servers/{serverId}/daemons/{daemonId}/restart

Firewall Rules

Create Rule

Payload

{ "name": "rule name", "ip_address": "192.168.1.1", "port": 88, "type": "allow" }

Response

{ "rule": { "id": 4, "name": "rule", "port": 123, "type": "allow", "ip_address": null, "status": "installing", "created_at": "2016-12-16 15:50:17" } }

HTTP Request

POST /api/v1/servers/{serverId}/firewall-rules

Available Rule Types

You may specify allow or deny as the rule type.

List Rules

Response

{ "rules": [ { "id": 4, "name": "rule", "port": 123, "type": "allow", "ip_address": null, "status": "installing", "created_at": "2016-12-16 15:50:17" } ] }

HTTP Request

GET /api/v1/servers/{serverId}/firewall-rules

Get Rule

Response

{ "rule": { "id": 4, "name": "rule", "port": 123, "type": "allow", "ip_address": null, "status": "installing", "created_at": "2016-12-16 15:50:17" } }

HTTP Request

GET /api/v1/servers/{serverId}/firewall-rules/{ruleId}

Delete Rule

HTTP Request

DELETE /api/v1/servers/{serverId}/firewall-rules/{ruleId}

Scheduled Jobs

Create Job

Payload

{ "command": "COMMAND_THE_JOB_RUNS", "frequency": "custom", "user": "root", "minute": "*", "hour": "*", "day": "*", "month": "*", "weekday": "*" }

Response

{ "job": { "id": 2, "command": "COMMAND_THE_JOB_RUNS", "user": "root", "frequency": "Nightly", "cron": "0 0 * * *", "status": "installing", "created_at": "2016-12-16 15:56:59" } }

HTTP Request

POST /api/v1/servers/{serverId}/jobs

Parameters

Key Description frequency The frequency in which the job should run. Valid values are minutely , hourly , nightly , weekly , monthly , reboot , and custom minute Required if the frequency is custom . hour Required if the frequency is custom . day Required if the frequency is custom . month Required if the frequency is custom . weekday Required if the frequency is custom .

List Jobs

Response

{ "jobs": [ { "id": 2, "command": "COMMAND_THE_JOB_RUNS", "user": "root", "frequency": "nightly", "cron": "0 0 * * *", "status": "installing", "created_at": "2016-12-16 15:56:59" } ] }

HTTP Request

GET /api/v1/servers/{serverId}/jobs

Get Job

Response

{ "job": { "id": 2, "command": "COMMAND_THE_JOB_RUNS", "user": "root", "frequency": "Nightly", "cron": "0 0 * * *", "status": "installing", "created_at": "2016-12-16 15:56:59" } }

HTTP Request

GET /api/v1/servers/{serverId}/jobs/{jobId}

Delete Job

HTTP Request

DELETE /api/v1/servers/{serverId}/jobs/{jobId}

PHP

List PHP Versions

Response

[ { "id": 29, "version": "php74", "status": "installed", "displayable_version": "PHP 7.4", "binary_name": "php7.4", "used_as_default": false, "used_on_cli": false }, { "id": 30, "version": "php73", "status": "installed", "displayable_version": "PHP 7.3", "binary_name": "php7.3", "used_as_default": true, "used_on_cli": true }, { "id": 31, "version": "php72", "status": "installed", "displayable_version": "PHP 7.2", "binary_name": "php7.2", "used_as_default": false, "used_on_cli": false }, { "id": 32, "version": "php71", "status": "installed", "displayable_version": "PHP 7.1", "binary_name": "php7.1", "used_as_default": false, "used_on_cli": false }, { "id": 33, "version": "php56", "status": "installed", "displayable_version": "PHP 5.6", "binary_name": "php5.6", "used_as_default": false, "used_on_cli": false } ]

HTTP Request

GET /api/v1/servers/{serverId}/php

Install PHP Version

HTTP Request

POST /api/v1/servers/{serverId}/php

Payload

{ "version": "php74" }

Available Versions

Key Description php56 PHP 5.6 php70 PHP 7.0 php71 PHP 7.1 php72 PHP 7.2 php73 PHP 7.3 php74 PHP 7.4

Upgrade PHP Patch Version

You must supply the version to be patched.

HTTP Request

POST /api/v1/servers/{serverId}/php/update

Payload

{ "version": "php74" }

Enable OPCache

HTTP Request

POST /api/v1/servers/{serverId}/php/opcache

Disable OPCache

HTTP Request

DELETE /api/v1/servers/{serverId}/php/opcache

Databases

Create Database

Payload

{ "name": "forge", "user": "forge", "password": "dolores" }

Response

{ "database": { "id": 1, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:12:22" } }

HTTP Request

POST /api/v1/servers/{serverId}/databases

Parameters

Key Description user This field is optional. If passed, it will be used to create a new Database User with access to the newly created database. password This field is only required when a user value is given.

List Databases

Response

{ "databases": [ { "id": 1, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:12:22" } ] }

HTTP Request

GET /api/v1/servers/{serverId}/databases

Get Database

Response

{ "database": { "id": 1, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:12:22" } }

HTTP Request

GET /api/v1/servers/{serverId}/databases/{databaseId}

Delete Database

HTTP Request

DELETE /api/v1/servers/{serverId}/databases/{databaseId}

Database Users

Create User

Payload

{ "name": "forge", "password": "dolores", "databases": [1] }

Response

{ "user": { "id": 2, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:19:01", "databases": [ 1 ] } }

HTTP Request

POST /api/v1/servers/{serverId}/database-users

Parameters

Key Description databases An array of database IDs referencing the databases the user has access to.

List Users

Response

{ "users": [ { "id": 2, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:19:01", "databases": [ 1 ] } ] }

HTTP Request

GET /api/v1/servers/{serverId}/database-users

Get User

Response

{ "user": { "id": 2, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:19:01", "databases": [ 1 ] } }

HTTP Request

GET /api/v1/servers/{serverId}/database-users/{userId}

Update User

Payload

{ "databases": [2] }

Response

{ "user": { "id": 2, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:19:01", "databases": [ 1 ] } }

HTTP Request

PUT /api/v1/servers/{serverId}/database-users/{userId}

This endpoint may be used to update the databases the Database User has access to.

Delete User

HTTP Request

DELETE /api/v1/servers/{serverId}/database-users/{userId}

MySQL Databases

The /mysql endpoints is now deprecated in favour of the new /databases endpoint.

Create Database

Payload

{ "name": "forge", "user": "forge", "password": "dolores" }

Response

{ "database": { "id": 1, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:12:22" } }

HTTP Request

POST /api/v1/servers/{serverId}/mysql

Parameters

Key Description user This field is optional. If passed, it will be used to create a new MySQL user with access to the newly created database. password This field is only required when a user value is given.

List Databases

Response

{ "databases": [ { "id": 1, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:12:22" } ] }

HTTP Request

GET /api/v1/servers/{serverId}/mysql

Get Database

Response

{ "database": { "id": 1, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:12:22" } }

HTTP Request

GET /api/v1/servers/{serverId}/mysql/{databaseId}

Delete Database

HTTP Request

DELETE /api/v1/servers/{serverId}/mysql/{databaseId}

MySQL Database Users

The /mysql-users endpoint is now deprecated in favour of the new /database-users endpoint.

Create User

Payload

{ "name": "forge", "password": "dolores", "databases": [1] }

Response

{ "user": { "id": 2, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:19:01", "databases": [ 1 ] } }

HTTP Request

POST /api/v1/servers/{serverId}/mysql-users

Parameters

Key Description databases An array of database IDs referencing the databases the user has access to.

List Users

Response

{ "users": [ { "id": 2, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:19:01", "databases": [ 1 ] } ] }

HTTP Request

GET /api/v1/servers/{serverId}/mysql-users

Get User

Response

{ "user": { "id": 2, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:19:01", "databases": [ 1 ] } }

HTTP Request

GET /api/v1/servers/{serverId}/mysql-users/{userId}

Update User

Payload

{ "databases": [2] }

Response

{ "user": { "id": 2, "name": "forge", "status": "installing", "created_at": "2016-12-16 16:19:01", "databases": [ 1 ] } }

HTTP Request

PUT /api/v1/servers/{serverId}/mysql-users/{userId}

This endpoint may be used to update the databases the MySQL user has access to.

Delete User

HTTP Request

DELETE /api/v1/servers/{serverId}/mysql-users/{userId}

Sites

Create Site

Payload

{ "domain": "site.com", "project_type": "php", "aliases": ["alias1.com", "alias2.com"], "directory": "/test", "isolated": true, "username": "laravel", "database": "site-com-db" }

Response

{ "site": { "id": 2, "name": "site.com", "aliases": ["alias1.com", "alias2.com"], "directory": "/test", "wildcards": false, "isolated": true, "username": "forge", "status": "installing", "repository": null, "repository_provider": null, "repository_branch": null, "repository_status": null, "quick_deploy": false, "project_type": "php", "app": null, "app_status": null, "slack_channel": null, "telegram_chat_id": null, "telegram_chat_title": null, "created_at": "2016-12-16 16:38:08", "deployment_url": "...", "tags": [] } }

HTTP Request

POST /api/v1/servers/{serverId}/sites

Available site types

Key Description php General PHP/Laravel Application. html Static HTML site. symfony Symfony Application. symfony_dev Symfony (Dev) Application. symfony_four Symfony >4.0 Application.

List Sites

Response

{ "sites": [ { "id": 2, "name": "site.com", "username": "laravel", "directory": "/test", "wildcards": false, "status": "installing", "repository": null, "repository_provider": null, "repository_branch": null, "repository_status": null, "quick_deploy": false, "project_type": "php", "app": null, "app_status": null, "slack_channel": null, "telegram_chat_id": null, "telegram_chat_title": null, "deployment_url": "...", "created_at": "2016-12-16 16:38:08", "tags": [] } ] }

HTTP Request

GET /api/v1/servers/{serverId}/sites

Get Site

Response

{ "site": { "id": 2, "name": "site.com", "aliases": ["alias1.com"], "username": "laravel", "directory": "/test", "wildcards": false, "status": "installing", "repository": null, "repository_provider": null, "repository_branch": null, "repository_status": null, "quick_deploy": false, "project_type": "php", "app": null, "app_status": null, "slack_channel": null, "telegram_chat_id": null, "telegram_chat_title": null, "deployment_url": "...", "created_at": "2016-12-16 16:38:08", "tags": [] } }

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}

Update Site

Payload

{ "directory": "/some/path", "name": "site-new-name.com", "aliases": ["alias1.com", "alias2.com"], "wildcards": true }

Response

{ "site": { "id": 2, "name": "site-new-name.com", "aliases": ["alias1.com", "alias2.com"], "username": "laravel", "directory": "/some/path", "wildcards": false, "status": "installing", "repository": null, "repository_provider": null, "repository_branch": null, "repository_status": null, "quick_deploy": false, "project_type": "php", "app": null, "app_status": null, "slack_channel": null, "telegram_chat_id": null, "telegram_chat_title": null, "deployment_url": "...", "created_at": "2016-12-16 16:38:08", "tags": [] } }

HTTP Request

PUT /api/v1/servers/{serverId}/sites/{siteId}

This endpoint is used to update the "web directory", primary name, aliases or whether to use wildcard sub-domains for a given site.

Change Site PHP Version

Payload

{ "version": "php74" }

HTTP Request

PUT /api/v1/servers/{serverId}/sites/{siteId}/php

Add Site Aliases

Payload

{ "aliases": ["alias1.com", "alias2.com"] }

Response

{ "site": { "id": 2, "name": "site.com", "aliases": ["alias1.com", "alias2.com"], "username": "laravel", "directory": "/", "wildcards": false, "status": "installing", "repository": null, "repository_provider": null, "repository_branch": null, "repository_status": null, "quick_deploy": false, "project_type": "php", "app": null, "app_status": null, "slack_channel": null, "telegram_chat_id": null, "telegram_chat_title": null, "deployment_url": "...", "created_at": "2016-12-16 16:38:08", "tags": [] } }

HTTP Request

PUT /api/v1/servers/{serverId}/sites/{siteId}/aliases

Use this endpoint to add additional site aliases and keep the exiting ones.

Delete Site

HTTP Request

DELETE /api/v1/servers/{serverId}/sites/{siteId}

Load Balancing

Payload

{ "servers": [{ "id": 2, "weight": 5 }, { "id": 3, "backup": true }, { "id": 4, "down": true }], "method": "least_conn" }

HTTP Request

PUT /api/v1/servers/{serverId}/sites/{siteId}/balancing

If the server is a load balancer, this endpoint may be used to specify the servers the load balancer should send traffic to.

Load Balancing Methods

Key Description round_robin Requests are evenly distributed across servers least_conn Requests are sent to the server with the least number of active connections ip_hash The server to which a request is sent is determined from the client IP address

Site Log

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/logs

Response

{ "content": "[2020-08-18 10:32:56] local.INFO: Test

" }

SSL Certificates

Create Certificate

Payload

{ "type": "new", "domain": "domain.com", "country": "US", "state": "NY", "city": "New York", "organization": "Company Name", "department": "IT" }

Response

{ "certificate": { "domain": "domain.com", "request_status": "creating", "created_at": "2016-12-17 07:02:35", "id": 3, "existing": false, "active": false } }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/certificates

Installing An Existing Certificate

Payload

{ "type": "existing", "key": "PRIVATE_KEY_HERE", "certificate": "CERTIFICATE_HERE" }

Response

{ "certificate": { "domain": "domain.com", "request_status": "creating", "created_at": "2016-12-17 07:02:35", "id": 3, "existing": false, "active": false } }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/certificates

Cloning An Existing Certificate

Payload

{ "type": "clone", "certificate_id": 1 }

Response

{ "certificate": { "domain": "domain.com", "request_status": "creating", "created_at": "2016-12-17 07:02:35", "id": 3, "existing": false, "active": false } }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/certificates

Obtain A LetsEncrypt Certificate

The dns_provider object is only required for wildcard sub-domains.

Payload

{ "domains": ["www.site.com"], "dns_provider": { "type": "xxx", "cloudflare_api_token": "xxx", "route53_key": "xxx", "route53_secret": "xxx", "digitalocean_token": "xxx", "dnssimple_token": "xxx", "linode_token": "xxx", "ovh_endpoint": "xxx", "ovh_app_key": "xxx", "ovh_app_secret": "xxx", "ovh_consumer_key": "xxx", "google_credentials_file": "xxx", } }

Response

{ "certificate": { "domain": "www.test.com", "type": "letsencrypt", "request_status": "created", "status": "installing", "created_at": "2017-02-09 17:14:34", "id": 1, "existing": true, "active": false } }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/certificates/letsencrypt

DNS Provider Types

Type Extra Fields cloudflare cloudflare_api_token . route53 route53_key and route53_secret digitalocean digitalocean_token dnssimple dnssimple_token linode linode_token ovh ovh_endpoint , ovh_app_key , ovh_app_secret and ovh_consumer_key google google_credentials_file

List Certificates

Response

{ "certificates": [ { "domain": "domain.com", "request_status": "creating", "created_at": "2016-12-17 07:02:35", "id": 3, "existing": false, "active": false } ] }

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/certificates

Get Certificate

Response

{ "certificate": { "domain": "domain.com", "request_status": "creating", "created_at": "2016-12-17 07:02:35", "id": 3, "existing": false, "active": false } }

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/certificates/{id}

Get Signing Request

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/certificates/{id}/csr

This endpoint may be used to get the full certificate signing request content.

Install Certificate

Payload

{ "certificate": "certificate content", "add_intermediates": false }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/certificates/{id}/install

Activate Certificate

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/certificates/{id}/activate

Delete Certificate

HTTP Request

DELETE /api/v1/servers/{serverId}/sites/{siteId}/certificates/{id}

SSH Keys

Create Key

Payload

{ "name": "test-key", "key": "KEY_CONTENT_HERE", "username": "forge" }

Response

{ "key": { "id": 9, "name": "test-key", "username": "forge", "status": "installing", "created_at": "2016-12-16 16:31:16" } }

HTTP Request

POST /api/v1/servers/{serverId}/keys

List Keys

Response

{ "keys": [ { "id": 9, "name": "test-key", "username": "forge", "status": "installing", "created_at": "2016-12-16 16:31:16" } ] }

HTTP Request

GET /api/v1/servers/{serverId}/keys

Get Key

Response

{ "key": { "id": 9, "name": "test-key", "username": "forge", "status": "installing", "created_at": "2016-12-16 16:31:16" } }

HTTP Request

GET /api/v1/servers/{serverId}/keys/{keyId}

Delete Key

HTTP Request

DELETE /api/v1/servers/{serverId}/keys/{keyId}

Workers

Create Worker

You may pass php as the php_version value to use the server's default PHP CLI version.

Payload

{ "connection": "sqs", "timeout": 90, "sleep": 60, "tries": null, "processes": 1, "daemon": true, "force": false, "php_version": "php72" }

Response

{ "worker": { "id": 1, "connection": "rule", "command": "php7.2 /home/forge/default/artisan queue:work rule --sleep=60 --daemon --quiet --timeout=90", "queue": null, "timeout": 90, "sleep": 60, "tries": null, "processes": 1, "environment": null, "php_version": "php72", "daemon": 1, "force": 0, "status": "installing", "created_at": "2016-12-17 07:15:03" } }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/workers

List Workers

Response

{ "workers": [ { "id": 1, "connection": "rule", "command": "php7.2 /home/forge/default/artisan queue:work rule --sleep=60 --daemon --quiet --timeout=90", "queue": null, "timeout": 90, "sleep": 60, "tries": null, "processes": 1, "environment": null, "php_version": "php72", "daemon": 1, "force": 0, "status": "installing", "created_at": "2016-12-17 07:15:03" } ] }

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/workers

Get Worker

Response

{ "worker": { "id": 1, "connection": "rule", "command": "php7.2 /home/forge/default/artisan queue:work rule --sleep=60 --daemon --quiet --timeout=90", "queue": null, "timeout": 90, "sleep": 60, "tries": null, "processes": 1, "environment": null, "php_version": "php72", "daemon": 1, "force": 0, "status": "installing", "created_at": "2016-12-17 07:15:03" } }

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/workers/{id}

Delete Worker

HTTP Request

DELETE /api/v1/servers/{serverId}/sites/{siteId}/workers/{id}

Restart Worker

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/workers/{id}/restart

Redirect Rules

Create Rule

Payload

{ "from": "/docs", "to": "/docs/1.1", "type": "redirect" }

Response

{ "redirect_rule": { "id": 15, "from": "/docs", "to": "/docs/1.1", "type": "redirect", "created_at": "2018-03-07 16:33:20" } }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/redirect-rules

Type Description redirect Creates a temporary 302 redirect permanent Create a permanent 301 redirect

List Redirect Rules

Response

{ "redirect_rules": [ { "id": 15, "from": "/docs", "to": "/docs/1.1", "type": "redirect", "created_at": "2018-03-07 16:33:20" } ] }

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/redirect-rules

Get Rule

Response

{ "redirect_rule": { "id": 15, "from": "/docs", "to": "/docs/1.1", "type": "redirect", "created_at": "2018-03-07 16:33:20" } }

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/redirect-rules/{id}

Delete Rule

HTTP Request

DELETE /api/v1/servers/{serverId}/sites/{siteId}/redirect-rules/{id}

Security Rules

Create Security Rule

Payload

{ "name": "Access Restricted", "path": null, "credentials": [ { "username": "taylor.otwell", "password": "password123" }, { "username": "james.brooks", "password": "secret123" } ] }

Response

{ "security_rule": { "id": 15, "name": "Access Restricted", "path": null, "created_at": "2020-07-30 10:11:10", "credentials": [ { "id": 20, "username": "taylor.otwell", "created_at": "2020-07-30 10:11:10" }, { "id": 21, "username": "james.brooks", "created_at": "2020-07-30 10:11:10" } ] } }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/security-rules

You may leave path empty to protect all routes within your site.

List Security Rules

Response

{ "security_rules": [ { "id": 15, "name": "Access Restricted", "path": null, "created_at": "2020-07-30 10:11:10", "credentials": [ { "id": 20, "username": "taylor.otwell", "created_at": "2020-07-30 10:11:10" }, { "id": 21, "username": "james.brooks", "created_at": "2020-07-30 10:11:10" } ] } ] }

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/security-rules

Get Security Rule

Response

{ "security_rule": { "id": 15, "name": "Access Restricted", "path": null, "created_at": "2020-07-30 10:11:10", "credentials": [ { "id": 20, "username": "taylor.otwell", "created_at": "2020-07-30 10:11:10" }, { "id": 21, "username": "james.brooks", "created_at": "2020-07-30 10:11:10" } ] } }

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/security-rules/{id}

Delete Security Rule

HTTP Request

DELETE /api/v1/servers/{serverId}/sites/{siteId}/security-rules/{id}

Deployment

Enable Quick Deployment

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/deployment

Disable Quick Deployment

HTTP Request

DELETE /api/v1/servers/{serverId}/sites/{siteId}/deployment

Get Deployment Script

The response is a string for this request.

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/deployment/script

Update Deployment Script

Payload

{ "content": "CONTENT_OF_THE_SCRIPT" }

HTTP Request

PUT /api/v1/servers/{serverId}/sites/{siteId}/deployment/script

Deploy Now

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/deployment/deploy

Reset Deployment Status

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/deployment/reset

Get Deployment Log

The response is a string for this request.

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/deployment/log

Configuration Files

Get Nginx Configuration

The response is a string for this request.

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/nginx

Update Nginx Configuration

Payload

{ "content": "CONTENT" }

HTTP Request

PUT /api/v1/servers/{serverId}/sites/{siteId}/nginx

Get .env File

The response is a string for this request.

HTTP Request

GET /api/v1/servers/{serverId}/sites/{siteId}/env

Update .env File

Payload

{ "content": "CONTENT" }

HTTP Request

PUT /api/v1/servers/{serverId}/sites/{siteId}/env

git Projects

Install New

Payload

{ "provider": "github", "repository": "username/repository", "branch": "master", "composer": tre }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/git

Parameters

Key Description provider The repository provider. Valid values are github , gitlab , bitbucket , and custom . composer Whether to install Composer dependencies. Valid values are true or false .

Update Repository

Payload

{ "provider": "github", "repository": "username/repository", "branch": "master" }

HTTP Request

PUT /api/v1/servers/{serverId}/sites/{siteId}/git

Remove Project

HTTP Request

DELETE /api/v1/servers/{serverId}/sites/{siteId}/git

WordPress

Install

Payload

{ "database": "forge", "user": 1 }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/wordpress

Uninstall WordPress

HTTP Request

DELETE /api/v1/servers/{serverId}/sites/{siteId}/wordpress

This endpoint will uninstall WordPress and revert the site back to a default state.

phpMyAdmin

Install

Payload

{ "database": "forge", "user": 1 }

HTTP Request

POST /api/v1/servers/{serverId}/sites/{siteId}/phpmyadmin

Uninstall phpMyAdmin

HTTP Request

DELETE /api/v1/servers/{serverId}/sites/{siteId}/phpmyadmin

This endpoint will uninstall phpMyAdmin and revert the site back to a default state.

Webhooks

List

Response

{ "webhooks": [ { "id": 10, "url": "http://domain.com", "created_at": "2018-10-10 17:01:18" } ] }

HTTP Request

GET /api/v1/servers/{server_id}/sites/{site_id}/webhooks

Show

Response

{ "webhook": { "id": 10, "url": "http://domain.com", "created_at": "2018-10-10 17:01:18" } }

HTTP Request

GET /api/v1/servers/{server_id}/sites/{site_id}/webhooks/{id}

Create

Response

{ "url": "http://domain.com" }

HTTP Request

POST /api/v1/servers/{server_id}/sites/{site_id}/webhooks

Delete

Response

{ "url": "http://domain.com" }

HTTP Request

DELETE /api/v1/servers/{server_id}/sites/{site_id}/webhooks/{id}

Recipes

Create Recipe

Payload

{ "name": "Recipe Name", "user": "root", "script": "SCRIPT_CONTENT" }

Response

{ "recipe": { "id": 1, "name": "Recipe Name", "user": "root", "script": "SCRIPT_CONTENT", "created_at": "2016-12-16 16:24:05" } }

HTTP Request

POST /api/v1/recipes

List Recipes

Response

{ "recipes": [ { "id": 1, "name": "Recipe Name", "user": "root", "script": "SCRIPT_CONTENT", "created_at": "2016-12-16 16:24:05" } ] }

HTTP Request

GET /api/v1/recipes

Get Recipe

Response

{ "recipe": { "id": 1, "name": "Recipe Name", "user": "root", "script": "SCRIPT_CONTENT", "created_at": "2016-12-16 16:24:05" } }

HTTP Request

GET /api/v1/recipes/{recipeId}

Update Recipe

Payload

{ "name": "Recipe Name", "user": "root", "script": "SCRIPT_CONTENT" }

Response

{ "recipe": { "id": 1, "name": "Recipe Name", "user": "root", "script": "SCRIPT_CONTENT", "created_at": "2016-12-16 16:24:05" } }

HTTP Request

PUT /api/v1/recipes/{recipeId}

Delete Recipe

HTTP Request

DELETE /api/v1/recipes/{recipeId}

Run Recipe

Payload

{ "servers": [1,2], "notify": true }

HTTP Request

POST /api/v1/recipes/{recipeId}/run

Regions

List

Response

{ "regions": { "ocean2": [ { "id": "ams2", "name": "Amsterdam 2", "sizes": [ { "id": "01", "size": "s-1vcpu-1gb", "name": "1GB RAM - 1 CPU Core - 25GB SSD" } ] } ], "linode": [], "vultr": [], "aws": [] } }

HTTP Request

GET /api/v1/regions

Credentials

List

Response

{ "credentials": [ { "id": 1, "type": "ocean2", "name": "Personal" } ] }

HTTP Request

GET /api/v1/credentials

Backups

List Backup Configurations

HTTP Request

GET /api/v1/servers/{serverId}/backup-configs

Response

{ "backups": [ { "id": 10, "day_of_week": null, "time": null, "provider" : "spaces", "provider_name": "DigitalOcean Spaces", "status": "installed", "databases": [{ "id": 100, "name": "forge", "status": "installed", "created_at": "2020-01-01 10:00:00" }], "backups": [ { "id": 144, "backup_id": 10, "status": "success", "restore_status": null, "archive_path": "s3://backup-configs/server/db/backup-10-20200101123601.tar.gz", "duration": 4, "date": "1st Jan 12:36 PM" } ], "last_backup_time": "3 days ago" } ] }

Create Backup Configuration

Payload

Response

{ "backup": { "id": 10, "day_of_week": null, "time": null, "provider" : "spaces", "provider_name": "DigitalOcean Spaces", "status": "installing", "databases": [ { "id": 24, "name": "forge", "status": "installed", "created_at": "2020-01-13 15:47:33" } ], "backups": [], "last_backup_time": null } }

HTTP Request

POST /api/v1/servers/{serverId}/backup-configs

Available providers

Key Description s3 Amazon S3 spaces DigitalOcean Spaces custom Custom (S3 Compatible, e.g. MinIO)

When supplying a custom provider, you must also provide an endpoint .

Frequency options

hourly

daily - you must supply a time in 24 hour format

- you must supply a in 24 hour format weekly - you must supply a time in 24 hour format and a day option 0 (Sunday) - 6 (Saturday)

- you must supply a in 24 hour format and a option 0 (Sunday) - 6 (Saturday) custom - you must supply a custom value, as a valid cron expression

Update Backup Configuration

Response

{ "backup": { "id": 10, "day_of_week": null, "time": null, "provider" : "spaces", "provider_name": "DigitalOcean Spaces", "status": "updating", "databases": [ { "id": 24, "name": "forge", "status": "installed", "created_at": "2020-01-13 15:47:33" } ], "backups": [], "last_backup_time": null } }

Get Backup Configuration

Response

{ "backup": { "id": 10, "day_of_week": null, "time": null, "provider" : "spaces", "provider_name": "DigitalOcean Spaces", "status": "installed", "databases": [ { "id": 24, "name": "forge", "status": "installed", "created_at": "2020-01-13 15:47:33" } ], "backups": [], "last_backup_time": null } }

HTTP Request

GET /api/v1/servers/{serverId}/backup-configs/{backupConfigurationId}

Run Backup Configuration

Manually run a backup configuration.

HTTP Request

POST /api/v1/servers/{serverId}/backup-configs/{backupConfigurationId}

Delete Backup Configuration

HTTP Request

DELETE /api/v1/servers/{serverId}/backup-configs/{backupConfigurationId}

Restore Backup

Payload

{ "database": 7 }

If no database value is provided, Forge will restore the first database available.

HTTP Request

POST /api/v1/servers/{serverId}/backup-configs/{backupConfigurationId}/backups/{backupId}

Delete Backup

HTTP Request

DELETE /api/v1/servers/{serverId}/backup-configs/{backupConfigurationId}/backups/{backupId}

Monitoring

List Monitors

HTTP Request

GET /api/v1/servers/{serverId}/monitors

Response

{ "monitors": [ { "id": 3, "status": "installed", "type": "free_memory", "operator": "lte", "threshold": 70, "minutes": 5, "state": "ALERT", "state_changed_at": "2020-03-01 12:45:00" }, { "id": 7, "status": "installed", "type": "disk", "operator": "lte", "threshold": 25, "minutes": 0, "state": "OK", "state_changed_at": "2020-03-01 12:45:00" } ] }

Create Monitor

Payload

Response

{ "monitor": { "id": 8, "status": "installed", "type": "disk", "operator": "lte", "threshold": 25, "minutes": 0, "state": "OK", "state_changed_at": "2020-03-01 12:45:00" } }

HTTP Request

POST /api/v1/servers/{serverId}/monitors

Available Monitors

Monitors work on a % value.

Key Description disk The used disk space used_memory The amount of used memory cpu_load The CPU load

Operators

gte - greater than or equal to

- greater than or equal to lte - less than or equal to

Get Monitor

HTTP Request

GET /api/v1/servers/{serverId}/monitors/{monitorId}

Response

{ "monitor": { "id": 3, "status": "installed", "type": "free_memory", "operator": "lte", "threshold": 70, "minutes": 5, "state": "ALERT", "state_changed_at": "2020-03-01 12:45:00" } }

Delete Monitor

HTTP Request

DELETE /api/v1/servers/{serverId}/monitors/{monitorId}

Server Logs

Get Log

HTTP Request

GET /api/v1/servers/{serverId}/logs

Response

{ "path": "\/var\/log\/mysql\/error.log", "content": "2020-08-18T10:22:01.238990Z 0 [System] [MY-010931] [Server] \/usr\/sbin\/mysqld: ready for connections. Version: '8.0.21' socket: '\/var\/run\/mysqld\/mysqld.sock' port: 3306 MySQL Community Server - GPL.

2020-08-18T10:22:01.359309Z 0 [System] [MY-013172] [Server] Received SHUTDOWN from user <via user signal>. Shutting down mysqld (Version: 8.0.21).

2020-08-18T10:22:03.644177Z 0 [System] [MY-010910] [Server] \/usr\/sbin\/mysqld: Shutdown complete (mysqld 8.0.21) MySQL Community Server - GPL.

2020-08-18T10:22:04.183385Z 0 [System] [MY-010116] [Server] \/usr\/sbin\/mysqld (mysqld 8.0.21) starting as process 42752

2020-08-18T10:22:04.193962Z 1 [System] [MY-013576] [InnoDB] InnoDB initialization has started.

2020-08-18T10:22:04.530305Z 1 [System] [MY-013577] [InnoDB] InnoDB initialization has ended.

2020-08-18T10:22:04.662877Z 0 [System] [MY-011323] [Server] X Plugin ready for connections. Bind-address: '::' port: 33060, socket: \/var\/run\/mysqld\/mysqlx.sock

2020-08-18T10:22:04.749019Z 0 [Warning] [MY-010068] [Server] CA certificate ca.pem is self signed.

2020-08-18T10:22:04.749453Z 0 [System] [MY-013602] [Server] Channel mysql_main configured to support TLS. Encrypted connections are now supported for this channel.

2020-08-18T10:22:04.775994Z 0 [System] [MY-010931] [Server] \/usr\/sbin\/mysqld: ready for connections. Version: '8.0.21' socket: '\/var\/run\/mysqld\/mysqld.sock' port: 3306 MySQL Community Server - GPL.

" }

File Types

You must specify one of the below file types: