Add service
curl --request POST \
--url https://api.instacloud.com/projects/{projectId}/services \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "postgres",
"name": "<string>",
"branch": "<string>",
"region": "us-east",
"public": true,
"image": "<string>",
"port": 123,
"alwaysOn": true,
"volumeMountPath": "<string>",
"volumeGib": 2
}
'import requests
url = "https://api.instacloud.com/projects/{projectId}/services"
payload = {
"type": "postgres",
"name": "<string>",
"branch": "<string>",
"region": "us-east",
"public": True,
"image": "<string>",
"port": 123,
"alwaysOn": True,
"volumeMountPath": "<string>",
"volumeGib": 2
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
type: 'postgres',
name: '<string>',
branch: '<string>',
region: 'us-east',
public: true,
image: '<string>',
port: 123,
alwaysOn: true,
volumeMountPath: '<string>',
volumeGib: 2
})
};
fetch('https://api.instacloud.com/projects/{projectId}/services', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.instacloud.com/projects/{projectId}/services",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'type' => 'postgres',
'name' => '<string>',
'branch' => '<string>',
'region' => 'us-east',
'public' => true,
'image' => '<string>',
'port' => 123,
'alwaysOn' => true,
'volumeMountPath' => '<string>',
'volumeGib' => 2
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.instacloud.com/projects/{projectId}/services"
payload := strings.NewReader("{\n \"type\": \"postgres\",\n \"name\": \"<string>\",\n \"branch\": \"<string>\",\n \"region\": \"us-east\",\n \"public\": true,\n \"image\": \"<string>\",\n \"port\": 123,\n \"alwaysOn\": true,\n \"volumeMountPath\": \"<string>\",\n \"volumeGib\": 2\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.instacloud.com/projects/{projectId}/services")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"postgres\",\n \"name\": \"<string>\",\n \"branch\": \"<string>\",\n \"region\": \"us-east\",\n \"public\": true,\n \"image\": \"<string>\",\n \"port\": 123,\n \"alwaysOn\": true,\n \"volumeMountPath\": \"<string>\",\n \"volumeGib\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instacloud.com/projects/{projectId}/services")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"postgres\",\n \"name\": \"<string>\",\n \"branch\": \"<string>\",\n \"region\": \"us-east\",\n \"public\": true,\n \"image\": \"<string>\",\n \"port\": 123,\n \"alwaysOn\": true,\n \"volumeMountPath\": \"<string>\",\n \"volumeGib\": 2\n}"
response = http.request(request)
puts response.read_body{
"service": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "postgres",
"name": "<string>",
"spec": {},
"machine_count": 123,
"desired_state": "running",
"always_on": true,
"websocket": true,
"region": "<string>",
"domain": "<string>",
"public": true,
"image": "<string>",
"port": 123,
"start_command": "<string>",
"volume_applied_mount_path": "<string>",
"volume_mount_path": "<string>",
"volume_gib": 123,
"pg_version": 123,
"template_deployment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"template_modified": true,
"template_code": "<string>",
"template_logo_url": "<string>",
"source": {
"type": "image",
"owner": "<string>",
"repo": "<string>",
"branch": "<string>",
"auto_deploy": true
},
"status": "creating",
"created_at": "2023-11-07T05:31:56Z"
},
"source": {
"type": "image",
"image": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"owner": "<string>",
"repo": "<string>",
"branch": "<string>",
"root_dir": "<string>",
"watch_paths": [
"<string>"
],
"auto_deploy": true,
"public": true,
"installation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"repo_id": "<string>",
"build_command": "<string>",
"start_command": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"last_build": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"source_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"repo_binding_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"service_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"commit_sha": "<string>",
"status": "queued",
"image_ref": "<string>",
"error": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
},
"build": {
"buildId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"queued": true,
"serviceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"nextActions": [
{
"op": "<string>",
"reason": "<string>",
"args": {},
"gated": true
}
]
}{
"status": "approval_required",
"approvalId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"action": "<string>",
"actions": [
"<string>"
],
"message": "<string>",
"url": "<string>",
"nextActions": [
{
"op": "<string>",
"reason": "<string>",
"args": {},
"gated": true
}
]
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}Services
Add service
Token scope: account · org · project — read-only tokens refused (not a GET).
Add a service on demand. Assigns a default access domain (postgres/compute). Gated — service.add.
POST
/
projects
/
{projectId}
/
services
Add service
curl --request POST \
--url https://api.instacloud.com/projects/{projectId}/services \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "postgres",
"name": "<string>",
"branch": "<string>",
"region": "us-east",
"public": true,
"image": "<string>",
"port": 123,
"alwaysOn": true,
"volumeMountPath": "<string>",
"volumeGib": 2
}
'import requests
url = "https://api.instacloud.com/projects/{projectId}/services"
payload = {
"type": "postgres",
"name": "<string>",
"branch": "<string>",
"region": "us-east",
"public": True,
"image": "<string>",
"port": 123,
"alwaysOn": True,
"volumeMountPath": "<string>",
"volumeGib": 2
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
type: 'postgres',
name: '<string>',
branch: '<string>',
region: 'us-east',
public: true,
image: '<string>',
port: 123,
alwaysOn: true,
volumeMountPath: '<string>',
volumeGib: 2
})
};
fetch('https://api.instacloud.com/projects/{projectId}/services', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.instacloud.com/projects/{projectId}/services",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'type' => 'postgres',
'name' => '<string>',
'branch' => '<string>',
'region' => 'us-east',
'public' => true,
'image' => '<string>',
'port' => 123,
'alwaysOn' => true,
'volumeMountPath' => '<string>',
'volumeGib' => 2
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.instacloud.com/projects/{projectId}/services"
payload := strings.NewReader("{\n \"type\": \"postgres\",\n \"name\": \"<string>\",\n \"branch\": \"<string>\",\n \"region\": \"us-east\",\n \"public\": true,\n \"image\": \"<string>\",\n \"port\": 123,\n \"alwaysOn\": true,\n \"volumeMountPath\": \"<string>\",\n \"volumeGib\": 2\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.instacloud.com/projects/{projectId}/services")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"postgres\",\n \"name\": \"<string>\",\n \"branch\": \"<string>\",\n \"region\": \"us-east\",\n \"public\": true,\n \"image\": \"<string>\",\n \"port\": 123,\n \"alwaysOn\": true,\n \"volumeMountPath\": \"<string>\",\n \"volumeGib\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instacloud.com/projects/{projectId}/services")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"postgres\",\n \"name\": \"<string>\",\n \"branch\": \"<string>\",\n \"region\": \"us-east\",\n \"public\": true,\n \"image\": \"<string>\",\n \"port\": 123,\n \"alwaysOn\": true,\n \"volumeMountPath\": \"<string>\",\n \"volumeGib\": 2\n}"
response = http.request(request)
puts response.read_body{
"service": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "postgres",
"name": "<string>",
"spec": {},
"machine_count": 123,
"desired_state": "running",
"always_on": true,
"websocket": true,
"region": "<string>",
"domain": "<string>",
"public": true,
"image": "<string>",
"port": 123,
"start_command": "<string>",
"volume_applied_mount_path": "<string>",
"volume_mount_path": "<string>",
"volume_gib": 123,
"pg_version": 123,
"template_deployment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"template_modified": true,
"template_code": "<string>",
"template_logo_url": "<string>",
"source": {
"type": "image",
"owner": "<string>",
"repo": "<string>",
"branch": "<string>",
"auto_deploy": true
},
"status": "creating",
"created_at": "2023-11-07T05:31:56Z"
},
"source": {
"type": "image",
"image": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"owner": "<string>",
"repo": "<string>",
"branch": "<string>",
"root_dir": "<string>",
"watch_paths": [
"<string>"
],
"auto_deploy": true,
"public": true,
"installation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"repo_id": "<string>",
"build_command": "<string>",
"start_command": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"last_build": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"source_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"repo_binding_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"service_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"commit_sha": "<string>",
"status": "queued",
"image_ref": "<string>",
"error": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
},
"build": {
"buildId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"queued": true,
"serviceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"nextActions": [
{
"op": "<string>",
"reason": "<string>",
"args": {},
"gated": true
}
]
}{
"status": "approval_required",
"approvalId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"action": "<string>",
"actions": [
"<string>"
],
"message": "<string>",
"url": "<string>",
"nextActions": [
{
"op": "<string>",
"reason": "<string>",
"args": {},
"gated": true
}
]
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}Authorizations
Session access JWT or an API token (insta_<prefix>_<secret>).
Path Parameters
Body
application/json
type
Option 1 · enum<string>Option 2 · enum<string>Option 3 · enum<string>Option 4 · enum<string>Option 5 · enum<string>Option 6 · enum<string>
required
Available options:
postgres lower-kebab: a-z, 0-9, hyphen
target branch (default: project default branch)
region for postgres/compute/managed databases (see GET /regions); invalid for storage
Available options:
us-east storage only — provision the bucket with anonymous public-read (default false)
compute only — container image to run at creation (e.g. nginx:1.27)
compute only — port the image listens on (default 8080)
compute only — idle mode at creation. Omitted: the platform default (INSTA_COMPUTE_ALWAYS_ON_DEFAULT; true on InstaCloud: machines never scale to zero). false = scale-to-zero: idle machines suspend and wake on request. All plans; billing is actual usage either way.
Compute only: container mount path chosen on attachment; defaults to /data. Requires volumeGib only when attaching. Existing path changes are staged until the next deploy.
compute only — attach a persistent volume of this many whole Gi (attachable later too via PUT /services/:id/volume; the volume never detaches, but DELETE /services/:id/volume destroys it, data and all). Any plan may create up to the configured free volume cap (10Gi by default, env-overridable per deployment); a larger size is paid and capped at the org's own plan cap (50Gi on paid plans by default), like growing it later. Constraints: machineCount stays 1, and scale-to-zero uses stop (cold wake) instead of suspend — both lift if the volume is deleted.
Required range:
x >= 1Show child attributes
Show child attributes
Response
Default Response
A project-level service (postgres | storage | compute | redis | mysql | mongodb).
Show child attributes
Show child attributes
Where a compute service’s running image comes from: an image somebody deployed (type=image, the absence of a connected source) or a connected repository (type=github).
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes