Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Meza-dev/Ghostly/llms.txt

Use this file to discover all available pages before exploring further.

The POST /v1/projects endpoint creates a new project and associates it with the authenticated user. A project acts as a logical container for test runs, allowing you to group, filter, and report results by feature area or application. Once created, the project’s UUID can be referenced in run payloads and list filters.

​
Authentication

All requests to /v1/projects require authentication. Pass credentials using one of the two supported schemes:
SchemeHeader
API KeyX-Api-Key: <your-key>
JWT (session)Authorization: Bearer <token>

​
Request body

Send a JSON body with the following fields:
​
label
string
required
Display name for the project. Must be a non-empty string after trimming whitespace. This value is shown in the dashboard and returned in run records.
​
color
string
Accent color for the project badge, expressed as a CSS hex value (e.g. "#10b981"). When omitted, the server defaults to "#6366f1".

​
Response — 201 Created

On success the server returns HTTP 201 with the newly created Project object.
​
id
string
required
Server-generated UUID for the new project.
​
label
string
required
The trimmed label exactly as stored.
​
color
string
required
The hex color that was saved. If you did not supply one, this will be "#6366f1".
​
createdAt
string
required
ISO 8601 timestamp of project creation.

​
Example response

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "label": "Checkout Flow",
  "color": "#10b981",
  "createdAt": "2025-06-01T09:15:00.000Z"
}

​
Response — 400 Bad Request

Returned when the request body cannot be parsed as JSON, or when label is absent or blank after trimming. When the body is not valid JSON: 
{
  "ok": false,
  "error": "cuerpo JSON inválido"
}
When label is missing or empty: 
{
  "ok": false,
  "error": "label requerido"
}
A label that consists only of whitespace characters is treated as empty and will return a 400 error. Always trim user input before sending it to this endpoint.

​
Examples

​
curl

curl -X POST https://your-ghostly-host/v1/projects \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"label": "Checkout Flow", "color": "#10b981"}'

​
TypeScript SDK

import { GhostlyClient } from "@ghostly/client";

const client = new GhostlyClient({
  baseUrl: "https://your-ghostly-host",
  apiKey: "your_api_key_here",
});

// With a custom color
const project = await client.createProject("Checkout Flow", "#10b981");

// Using the default color (#6366f1)
const defaultProject = await client.createProject("Marketing Site");

console.log(`Created project: ${project.id}`);
Store the returned id in your test configuration or .env file so you can pass it as the project field when starting runs via client.startRun(...).

Build docs developers (and LLMs) love

Get started for freeTalk to us