Create Workspace
curl --request POST \
--url https://api.velt.dev/v2/workspace/create \
--header 'Content-Type: application/json' \
--data '
{
"data": {
"ownerEmail": "<string>",
"name": "<string>",
"workspaceName": "<string>",
"avatar": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/workspace/create"
payload = { "data": {
"ownerEmail": "<string>",
"name": "<string>",
"workspaceName": "<string>",
"avatar": "<string>"
} }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
data: {
ownerEmail: '<string>',
name: '<string>',
workspaceName: '<string>',
avatar: '<string>'
}
})
};
fetch('https://api.velt.dev/v2/workspace/create', 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.velt.dev/v2/workspace/create",
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([
'data' => [
'ownerEmail' => '<string>',
'name' => '<string>',
'workspaceName' => '<string>',
'avatar' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"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.velt.dev/v2/workspace/create"
payload := strings.NewReader("{\n \"data\": {\n \"ownerEmail\": \"<string>\",\n \"name\": \"<string>\",\n \"workspaceName\": \"<string>\",\n \"avatar\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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.velt.dev/v2/workspace/create")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"ownerEmail\": \"<string>\",\n \"name\": \"<string>\",\n \"workspaceName\": \"<string>\",\n \"avatar\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/workspace/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"ownerEmail\": \"<string>\",\n \"name\": \"<string>\",\n \"workspaceName\": \"<string>\",\n \"avatar\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Workspace created successfully",
"data": {
"id": "workspace_abc123",
"name": "My Workspace",
"owner": {
"email": "owner@example.com",
"id": "owner_id_123",
"name": "John Doe",
"avatar": "https://example.com/avatar.png"
},
"authToken": "9a1b2c3d4e5f60718293a4b5c6d7e8f9",
"apiKeyList": {
"velt_api_key_1": {
"apiKeyName": "Owner Test API Key",
"id": "velt_api_key_1",
"type": "testing"
}
}
}
}
}
Account Creation and Verification
Create Workspace
POST
/
v2
/
workspace
/
create
Create Workspace
curl --request POST \
--url https://api.velt.dev/v2/workspace/create \
--header 'Content-Type: application/json' \
--data '
{
"data": {
"ownerEmail": "<string>",
"name": "<string>",
"workspaceName": "<string>",
"avatar": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/workspace/create"
payload = { "data": {
"ownerEmail": "<string>",
"name": "<string>",
"workspaceName": "<string>",
"avatar": "<string>"
} }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
data: {
ownerEmail: '<string>',
name: '<string>',
workspaceName: '<string>',
avatar: '<string>'
}
})
};
fetch('https://api.velt.dev/v2/workspace/create', 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.velt.dev/v2/workspace/create",
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([
'data' => [
'ownerEmail' => '<string>',
'name' => '<string>',
'workspaceName' => '<string>',
'avatar' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"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.velt.dev/v2/workspace/create"
payload := strings.NewReader("{\n \"data\": {\n \"ownerEmail\": \"<string>\",\n \"name\": \"<string>\",\n \"workspaceName\": \"<string>\",\n \"avatar\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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.velt.dev/v2/workspace/create")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"ownerEmail\": \"<string>\",\n \"name\": \"<string>\",\n \"workspaceName\": \"<string>\",\n \"avatar\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/workspace/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"ownerEmail\": \"<string>\",\n \"name\": \"<string>\",\n \"workspaceName\": \"<string>\",\n \"avatar\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Workspace created successfully",
"data": {
"id": "workspace_abc123",
"name": "My Workspace",
"owner": {
"email": "owner@example.com",
"id": "owner_id_123",
"name": "John Doe",
"avatar": "https://example.com/avatar.png"
},
"authToken": "9a1b2c3d4e5f60718293a4b5c6d7e8f9",
"apiKeyList": {
"velt_api_key_1": {
"apiKeyName": "Owner Test API Key",
"id": "velt_api_key_1",
"type": "testing"
}
}
}
}
}
Use this API to programmatically create a new Velt workspace. Protected by IP-based rate limiting and disposable email domain blocking.
This is a public endpoint — no authentication headers are required.
Endpoint
POST https://api.velt.dev/v2/workspace/create
Body
Params
object
required
Show properties
Show properties
string
required
Email address of the workspace owner. Disposable email domains are blocked.
string
Owner’s display name. Max 200 characters. Must not be empty when provided. Defaults to the owner’s email address when not provided.
string
Workspace name. Max 200 characters. Must not be empty when provided. Defaults to
"{name} workspace" when not provided (or "{ownerEmail} workspace" if name is also omitted).string
URL for the workspace owner’s avatar image. Max 2000 characters. Returned in the response as
owner.avatar.Example Request
{
"data": {
"ownerEmail": "owner@example.com",
"name": "John Doe",
"workspaceName": "My Workspace",
"avatar": "https://example.com/avatar.png"
}
}
Example Response
Success Response
{
"result": {
"status": "success",
"message": "Workspace created successfully",
"data": {
"id": "workspace_abc123",
"name": "My Workspace",
"owner": {
"email": "owner@example.com",
"id": "owner_id_123",
"name": "John Doe",
"avatar": "https://example.com/avatar.png"
},
"authToken": "9a1b2c3d4e5f60718293a4b5c6d7e8f9",
"apiKeyList": {
"velt_api_key_1": {
"apiKeyName": "Owner Test API Key",
"id": "velt_api_key_1",
"type": "testing"
}
}
}
}
}
apiKeyList is a keyed object (not an array). Each key is the API key ID. To extract the first API key, use Object.keys(result.data.apiKeyList)[0] in JavaScript or iterate over the object keys.The default
apiKeyName is derived from the part of ownerEmail before the @ (capitalized), not from name. For example, owner@example.com produces "Owner Test API Key".Failure Response
If email domain is disposable
{
"error": {
"status": "INVALID_ARGUMENT",
"message": "This email domain is not supported."
}
}
If rate limit exceeded
{
"error": {
"status": "RESOURCE_EXHAUSTED",
"message": "Rate limit exceeded for this endpoint. Try again later."
}
}
If the email already owns the maximum number of workspaces
An email address may own up to 5 workspaces.{
"error": {
"status": "RESOURCE_EXHAUSTED",
"message": "You have reached the maximum number of workspaces allowed for this email address."
}
}
If creating an additional workspace without a paid plan
The first workspace for an email is always allowed. Creating an additional workspace requires the email’s root workspace to be on a paid plan.{
"error": {
"status": "PERMISSION_DENIED",
"message": "Creating an additional workspace requires your root workspace to be on a paid plan (a production API key)."
}
}
If a workspace already exists for the email
{
"error": {
"status": "ALREADY_EXISTS",
"message": "A workspace already exists for this email address"
}
}
If workspace creation fails
{
"error": {
"status": "INTERNAL",
"message": "Failed to create workspace"
}
}
Next Steps
After creating a workspace, use the response values for subsequent API calls:- Workspace-level endpoints (e.g., Get Workspace, Create API Key): pass
result.data.idas thex-velt-workspace-idheader andresult.data.authTokenas thex-velt-workspace-auth-tokenheader. - API-key-level endpoints (e.g., Add Domains, Update Email Config): extract the API key ID from
Object.keys(result.data.apiKeyList)[0], then retrieve its auth token via Get Auth Tokens. Pass these asx-velt-api-keyandx-velt-auth-token.
{
"result": {
"status": "success",
"message": "Workspace created successfully",
"data": {
"id": "workspace_abc123",
"name": "My Workspace",
"owner": {
"email": "owner@example.com",
"id": "owner_id_123",
"name": "John Doe",
"avatar": "https://example.com/avatar.png"
},
"authToken": "9a1b2c3d4e5f60718293a4b5c6d7e8f9",
"apiKeyList": {
"velt_api_key_1": {
"apiKeyName": "Owner Test API Key",
"id": "velt_api_key_1",
"type": "testing"
}
}
}
}
}
Was this page helpful?

