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"
        }
      }
    }
  }
}

POST

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

data

object

required

Show properties

ownerEmail

string

required

Email address of the workspace owner. Disposable email domains are blocked.

name

string

Owner’s display name. Max 200 characters. Must not be empty when provided. Defaults to the owner’s email address when not provided.

workspaceName

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).

avatar

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.id as the x-velt-workspace-id header and result.data.authToken as the x-velt-workspace-auth-token header.
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 as x-velt-api-key and x-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"
        }
      }
    }
  }
}

List Agent Executions Get Workspace

⌘I

​Endpoint

​Body

​Params

​Example Request

​Example Response

​Success Response

​Failure Response

If email domain is disposable

If rate limit exceeded

If the email already owns the maximum number of workspaces

If creating an additional workspace without a paid plan

If a workspace already exists for the email

If workspace creation fails

​Next Steps

Endpoint

Body

Params

Example Request

Example Response

Success Response

Failure Response

Next Steps