# Cobonaut REST API Reference

---
# Agent Bootstrap Endpoint (Punkt startowy dla Agentów AI)
ID: api-start

## English
# Agent Bootstrap Endpoint (Service Discovery)

Before starting any operations with Cobonaut, the agent should call the public bootstrap endpoint. It requires no authentication and returns all the information needed to get started.

## Endpoint
* **Method:** \`GET\`
* **URL:** \`https://api.cobonaut.com/v1/start\` (calling the root address \`https://api.cobonaut.com/\` automatically redirects to this start endpoint)
* **Authorization:** None (public)

## What does it return?
The JSON response includes:
* **platform** — platform name and version
* **supportedPlatforms** — list of supported platforms (key and description), useful for customizing instructions for agents
* **templates** — current list of available project templates (key, name, description)
* **scenarios** — decision tree with three scenarios:
  * \`noAccount\` — user has no account → registration steps with ready-made URLs
  * \`hasAccountNoProject\` — has account but no project → create project and deploy
  * \`hasProject\` — has existing project (cobonaut.json) → edit code and redeploy
* **configFileSpec** — cobonaut.json configuration and local .cob.env file specifications (along with .gitignore guidance)
* **authInfo** — authorization header format
* **docsUrl / apiDocsUrl / llmDocsUrl** — links to full documentation

## Recommendation for AI Agents
1. **First step:** Call \`GET /v1/start\` to discover available templates and scenarios.
2. **Check context:** Does the project have a \`cobonaut.json\` file? Does the user have an API token?
3. **Pick a scenario:** Based on the \`detection\` fields in the response, choose the right path.
4. **Follow the steps:** Each scenario contains a \`steps\` array with ready-made URLs, HTTP methods, and parameters.

## Polish
# Punkt startowy dla Agentów AI (Service Discovery)

Zanim agent zacznie jakiekolwiek operacje z Cobonaut, powinien wywołać publiczny endpoint startowy. Nie wymaga on uwierzytelnienia i zwraca wszystkie informacje potrzebne do rozpoczęcia pracy.

## Endpoint
* **Metoda:** \`GET\`
* **URL:** \`https://api.cobonaut.com/v1/start\` (wywołanie głównego adresu \`https://api.cobonaut.com/\` automatycznie przekieruje na ten start)
* **Autoryzacja:** Brak (publiczny)

## Co zwraca?
Odpowiedź JSON zawiera:
* **platform** — nazwa platformy i wersja
* **supportedPlatforms** — lista wspieranych platform (klucz i opis), przydatnych do dopasowania instrukcji dla agentów
* **templates** — aktualna lista dostępnych szablonów projektów (key, name, description)
* **scenarios** — drzewo decyzyjne z trzema scenariuszami:
  * \`noAccount\` — użytkownik nie ma konta → kroki rejestracji z gotowymi URL
  * \`hasAccountNoProject\` — ma konto, ale nie ma projektu → tworzenie projektu i deploy
  * \`hasProject\` — ma projekt (cobonaut.json) → edycja kodu i redeploy
* **configFileSpec** — specyfikacja pliku konfiguracyjnego cobonaut.json oraz lokalnego .cob.env (wraz z instrukcją dla .gitignore)
* **authInfo** — format nagłówka autoryzacji
* **docsUrl / apiDocsUrl / llmDocsUrl** — linki do pełnej dokumentacji

## Rekomendacja dla Agentów AI
1. **Pierwszy krok:** Wywołaj \`GET /v1/start\` aby poznać dostępne szablony i scenariusze.
2. **Sprawdź kontekst:** Czy w projekcie istnieje plik \`cobonaut.json\`? Czy użytkownik ma token API?
3. **Wybierz scenariusz:** Na podstawie pól \`detection\` w odpowiedzi wybierz właściwą ścieżkę.
4. **Postępuj krok po kroku:** Każdy scenariusz zawiera tablicę \`steps\` z gotowymi URL, metodami HTTP i parametrami.


---
# API Authentication (Uwierzytelnianie API)
ID: api-auth

## English
# API Authentication

Cobonaut provides an external API (api.cobonaut.com) designed for external CLI tools, automation scripts, and third-party integrations. It uses a persistent API Token generated in settings.

### Authorization Header Format
```http
Authorization: Bearer cobo_live_[token]
```

### How to acquire your API key?
Navigate to Settings (/settings), check the box "Chcę używać Cobonaut przez zewnętrzne API" and copy the generated token. You can regenerate it at any time.

## Polish
# Uwierzytelnianie API

Cobonaut udostępnia zewnętrzne API (api.cobonaut.com) przeznaczone dla zewnętrznych narzędzi CLI, skryptów automatyzacji oraz integracji zewnętrznych. Używa ono trwałego tokenu API generowanego w ustawieniach.

### Format nagłówka autoryzacji
```http
Authorization: Bearer cobo_live_[token]
```

### Jak pozyskać klucz?
Przejdź do zakładki Ustawienia (/settings), zaznacz checkbox "Chcę używać Cobonaut przez zewnętrzne API" i skopiuj wygenerowany token. Możesz go w każdej chwili zresetować.


---
# Dedicated Deploy API (Dedykowany API Deploy)
ID: api-deploy

## English
# Dedicated REST API (api.cobonaut.com)

Cobonaut provides a set of public REST endpoints to facilitate integration with external CI/CD pipelines, AI agents (such as Antigravity), and scripts.

All requests must be authenticated using the following header:
```http
Authorization: Bearer cobo_live_[token]
```

---

## 1. List Templates
Returns the list of all available system templates.

* **Method:** `GET`
* **URL:** `https://api.cobonaut.com/v1/templates`

---

## 2. List Projects
Returns the list of all your projects.

* **Method:** `GET`
* **URL:** `https://api.cobonaut.com/v1/projects`

### Example Response
```json
{
  "success": true,
  "projects": [
    {
      "id": "uuid-project-1",
      "name": "My Application",
      "templateKey": "nextjs-basic-app",
      "createdAt": "2026-06-12T16:00:00.000Z",
      "updatedAt": "2026-06-12T16:00:00.000Z"
    }
  ]
}
```

---

## 3. Create Project
Creates a new project and seeds its Git repository from the selected template. Also returns the git repository URL.

* **Method:** `POST`
* **URL:** `https://api.cobonaut.com/v1/projects`
* **Content-Type:** `application/json`

### Request Body Parameters:
* `name` (string, required) - Project name.
* `templateKey` (string, required) - Template key (e.g. `nextjs-basic-app`, `wordpress`).

### Example Response
```json
{
  "id": "uuid-project",
  "name": "New Project",
  "templateKey": "nextjs-basic-app",
  "gitAccessToken": "ab12cd",
  "createdAt": "2026-06-12T16:00:00.000Z",
  "updatedAt": "2026-06-12T16:00:00.000Z",
  "repoUrl": "https://git.cobonaut.com/username/uuid-project.git",
  "authenticatedRepoUrl": "https://username:git_token_xyz@git.cobonaut.com/username/uuid-project.git",
  "settingsUrl": "https://cobonaut.com/workspace/uuid-project/settings",
  "workspaceUrl": "https://cobonaut.com/workspace/uuid-project",
  "confUrl": "https://api.cobonaut.com/v1/projects/uuid-project/conf",
  "instruction": "Create a cobonaut.json file in the root of the project and save the configuration (projectId, gitToken, repoUrl, etc.). The user can manually manage the project in the settings panel at: https://cobonaut.com/workspace/uuid-project/settings. In the main workspace panel (https://cobonaut.com/workspace/uuid-project), they can use the built-in Cobonaut IDE for remote management and development of the project. To retrieve the configuration or generate a new Git token (token reset), call GET/POST on the project configuration endpoint (confUrl): https://api.cobonaut.com/v1/projects/uuid-project/conf."
}
```

---

## 4. Get and Manage Project Configuration
Used to retrieve an existing project's metadata and configuration, or to reset/regenerate the project-specific Git access token.

### A. Get Project Configuration (GET)
Returns the current project configuration. If the project does not have a Git token generated yet (e.g. after migration or on first query), the server automatically generates one and returns it in the response.

* **Method:** `GET`
* **URL:** `https://api.cobonaut.com/v1/projects/[projectId]/conf`

#### Example Response (when a token is generated):
```json
{
  "id": "uuid-project",
  "name": "New Project",
  "templateKey": "nextjs-basic-app",
  "gitAccessToken": "ab12cd",
  "createdAt": "2026-06-12T16:00:00.000Z",
  "updatedAt": "2026-06-12T16:00:00.000Z",
  "repoUrl": "https://git.cobonaut.com/username/uuid-project.git",
  "authenticatedRepoUrl": "https://username:git_token_value@git.cobonaut.com/username/uuid-project.git",
  "settingsUrl": "https://cobonaut.com/workspace/uuid-project/settings",
  "workspaceUrl": "https://cobonaut.com/workspace/uuid-project",
  "instruction": "Utwórz w katalogu głównym projektu plik cobonaut.json i zapisz w nim konfigurację (projectId, gitToken, repoUrl itp.), aby nie utracić dostępu do Git.",
  "gitToken": "git_token_value"
}
```

### B. Reset/Regenerate Git Token (POST)
Invalidates the existing Git token and generates a new one. Returns the new plain-text token in the `gitToken` field.

* **Method:** `POST`
* **URL:** `https://api.cobonaut.com/v1/projects/[projectId]/conf`

#### Example Response:
```json
{
  "id": "uuid-project",
  "name": "New Project",
  "templateKey": "nextjs-basic-app",
  "gitAccessToken": "ef56gh",
  "createdAt": "2026-06-12T16:00:00.000Z",
  "updatedAt": "2026-06-12T16:00:00.000Z",
  "repoUrl": "https://git.cobonaut.com/username/uuid-project.git",
  "authenticatedRepoUrl": "https://username:new_git_token_value@git.cobonaut.com/username/uuid-project.git",
  "settingsUrl": "https://cobonaut.com/workspace/uuid-project/settings",
  "workspaceUrl": "https://cobonaut.com/workspace/uuid-project",
  "instruction": "Utwórz w katalogu głównym projektu plik cobonaut.json i zapisz w nim konfigurację (projectId, gitToken, repoUrl itp.), aby nie utracić dostępu do Git.",
  "gitToken": "new_git_token_value"
}
```

---

## 5. Initialize Deployment (First Deploy)
Creates and initializes the first project deployment (assigns a unique name and starts the container).

* **Method:** `POST`
* **URL:** `https://api.cobonaut.com/v1/deployments`
* **Content-Type:** `application/json`

### Request Body Parameters:
* `projectId` (string, required) - Project ID.
* `appName` (string, required) - Unique subdomain name on cloud.cobonaut.com.
* `serverSizeKey` (string, optional) - Server size (e.g. `free`, `eco`, `standard`). Defaults to `free`.
* `type` (string, optional) - Type of deployment environment (e.g. `prod`, `pre-prod`, `test`, `dev`). Defaults to `dev`.
* `customDomain` (string, optional) - Custom domain name to connect (e.g. `yourdomain.com`).
* `buyDomainIfAvailable` (boolean, optional) - Set to `true` to automatically register the domain in OVH (requires contact details).
* `contact` (object, optional) - Subscriber contact details for domain registration.

### Example Response (Standard)
```json
{
  "success": true,
  "deployment": {
    "id": "uuid-deployment",
    "projectId": "uuid-project",
    "appName": "my-app",
    "status": "pending",
    "url": "https://my-app.cloud.cobonaut.com",
    "serverSizeKey": "free"
  }
}
```

### Example Response (Awaiting Domain Purchase)
```json
{
  "status": "AWAITING_CONFIRMATION",
  "actionId": "uuid-action",
  "deploymentId": "uuid-deployment",
  "deploymentUrl": "https://my-app.cloud.cobonaut.com",
  "instructionForUser": "I have initiated the deployment with a domain purchase...",
  "message": "Deployment initiated on system domain. Awaiting domain purchase confirmation."
}
```

### Example Response (External Registrar)
```json
{
  "id": "uuid-deployment",
  "status": "AWAITING_DNS_CONFIGURATION",
  "dnsInstructions": {
    "message": "Configure DNS records at your registrar...",
    "records": [
      { "type": "A", "host": "@", "value": "51.83.162.89", "ttl": 3600 },
      { "type": "CNAME", "host": "www", "value": "yourdomain.com", "ttl": 3600 }
    ],
    "verifyUrl": "/api/deployments/uuid-deployment/custom-domain"
  }
}
```

---

## 6. Trigger Deployment / Redeploy
Triggers the code update and build procedure on the cluster.

* **Method:** `POST`
* **URL:** `https://api.cobonaut.com/v1/deploy`
* **Content-Type:** `application/json`

### Request Body Parameters:
* `appName` (string, optional/required interchangeably with projectId) - Name of the application subdomain (e.g. "my-app").
* `projectId` (string, optional/required interchangeably with appName) - ID of the project.
* `commitSha` (string, optional) - SHA of the commit to deploy. If omitted, the endpoint retrieves the latest HEAD commit from the git repository main branch.
* `update` (boolean, optional) - Forces updating and overwriting configuration and start scripts (like Dockerfile, captain-definition, entrypoint-setup.sh) from the latest system template directory. Highly useful for self-healing/updating legacy deployments.
* `clean` (boolean, optional) - Forces a clean reinstall by resetting the WordPress database (calling `wp db reset`) and running the installer from scratch on the next deployment using the configuration from `wordpress.json`. **Warning**: This parameter is completely ignored if the deployment type is set to `prod`.

### Example curl Request
```bash
curl -X POST https://api.cobonaut.com/v1/deploy \
  -H "Authorization: Bearer cobo_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my-app"
  }'
```

### Example Response (HTTP 202 Accepted)
```json
{
  "message": "Deployment procedure initiated",
  "deploymentId": "uuid-deployment",
  "appName": "my-app",
  "status": "deploying",
  "commitSha": "4ca52ba47e668858f1be467d216738fd410b0123",
  "commitMessage": "chore: updates index page",
  "statusUrl": "https://api.cobonaut.com/v1/deployments/uuid-deployment/status",
  "manageUrl": "https://cobonaut.com/cloud/uuid-deployment",
  "instruction": "Once deployment completes successfully, inform the user they can manually manage this deployment in the dashboard at: https://cobonaut.com/cloud/uuid-deployment"
}
```

---

## 7. Check Deployment Status
Returns the current build/running status of the container.

* **Method:** `GET`
* **URL:** `https://api.cobonaut.com/v1/deployments/[deploymentId]/status`

### Example Response
```json
{
  "success": true,
  "deploymentId": "uuid-deployment",
  "appName": "my-app",
  "status": "running",
  "commitSha": "4ca52ba47e668858f1be467d216738fd410b0123",
  "url": "https://my-app.cloud.cobonaut.com"
}
```

---

## 8. Get Deployment Runtime Logs
Returns the last 200 lines of runtime output (stdout/stderr) from the running application container. This is extremely useful for AI agents to diagnose database connection issues, crash loops, or other server-side startup failures.

* **Method:** `GET`
* **URL:** `https://api.cobonaut.com/v1/deployments/[deploymentId]/logs`

### Example Response
```json
{
  "logs": [
    "PrismaClientInitializationError: Environment variable not found: DATABASE_URL.",
    "    at ...",
    "Application crashed, exiting."
  ]
}
```

---

## 9. API Server Status (Healthcheck)
Public diagnostic endpoint for API server health status.

* **Method:** `GET`
* **URL:** `https://api.cobonaut.com/v1/health`

---

## 10. Get User Profile
Returns basic profile details of the logged-in user.

* **Method:** `GET`
* **URL:** `https://api.cobonaut.com/v1/me`

### Example Response
```json
{
  "success": true,
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "name": "John Doe",
    "isVerified": true,
    "apiEnabled": true
  },
  "instruction": "Dostęp do repozytorium git projektu jest przydzielany indywidualnie per-projekt w odpowiedzi z endpointu tworzenia projektu (POST /v1/projects) lub pobierania szczegółów konfiguracji projektu (GET /v1/projects/[id]/conf)."
}
```

---

## 11. Change Deployment Domain
Changes the custom domain connected to an existing deployment.

* **Method:** `POST`
* **URL:** `https://api.cobonaut.com/v1/deployments/[deploymentId]/change-domain`
* **Content-Type:** `application/json`

### Request Body Parameters:
* `domain` (string, required) - New custom domain name.
* `buyDomainIfAvailable` (boolean, optional) - Set to `true` to automatically register the domain.
* `contact` (object, optional) - Subscriber contact details.

---

## 12. Detach Custom Domain
Detaches the custom domain from a deployment, returning the app URL to the system subdomain (*.cloud.cobonaut.com). Creates a free approval request.

* **Method:** `POST`
* **URL:** `https://api.cobonaut.com/v1/deployments/[deploymentId]/detach-domain`
`

## Polish
# Dedykowany Interfejs API (api.cobonaut.com)

Cobonaut udostępnia zestaw publicznych endpointów REST ułatwiających integrację z zewnętrznymi systemami CI/CD, agentami AI oraz skryptami.

Wszystkie chronione zapytania muszą być uwierzytelnione za pomocą nagłówka:
```http
Authorization: Bearer cobo_live_[token]
```

---

## 1. Pobieranie listy szablonów
Zwraca listę wszystkich dostępnych szablonów w systemie.

* **Metoda:** `GET`
* **URL:** `https://api.cobonaut.com/v1/templates`

---

## 2. Pobieranie listy projektów
Zwraca listę wszystkich Twoich projektów.

* **Metoda:** `GET`
* **URL:** `https://api.cobonaut.com/v1/projects`

### Przykład odpowiedzi
```json
{
  "success": true,
  "projects": [
    {
      "id": "uuid-projektu-1",
      "name": "Moja Aplikacja",
      "templateKey": "nextjs-basic-app",
      "createdAt": "2026-06-12T16:00:00.000Z",
      "updatedAt": "2026-06-12T16:00:00.000Z"
    }
  ]
}
```

---

## 3. Tworzenie nowego projektu
Zakłada nowy projekt i automatycznie inicjalizuje repozytorium kodu z wybranego szablonu. Zwraca również adres URL do repozytorium Git.

* **Metoda:** `POST`
* **URL:** `https://api.cobonaut.com/v1/projects`
* **Content-Type:** `application/json`

### Parametry w body:
* `name` (string, wymagany) - Nazwa projektu.
* `templateKey` (string, wymagany) - Klucz szablonu (np. `nextjs-basic-app`, `wordpress`).

### Przykład odpowiedzi
```json
{
  "id": "uuid-projektu",
  "name": "Nowy Projekt",
  "templateKey": "nextjs-basic-app",
  "gitAccessToken": "ab12cd",
  "createdAt": "2026-06-12T16:00:00.000Z",
  "updatedAt": "2026-06-12T16:00:00.000Z",
  "repoUrl": "https://git.cobonaut.com/nazwa_uzytkownika/uuid-projektu.git",
  "authenticatedRepoUrl": "https://nazwa_uzytkownika:token_git_xyz@git.cobonaut.com/nazwa_uzytkownika/uuid-projektu.git",
  "settingsUrl": "https://cobonaut.com/workspace/uuid-projektu/settings",
  "workspaceUrl": "https://cobonaut.com/workspace/uuid-projektu",
  "confUrl": "https://api.cobonaut.com/v1/projects/uuid-projektu/conf",
  "instruction": "Utwórz w katalogu głównym projektu plik cobonaut.json i zapisz w nim konfigurację (projectId, gitToken, repoUrl itp.). Użytkownik może ręcznie zarządzać projektem pod linkiem ustawień: https://cobonaut.com/workspace/uuid-projektu/settings. W głównym panelu workspace (https://cobonaut.com/workspace/uuid-projektu) może korzystać z wbudowanego IDE Cobonaut do zdalnego prowadzenia i rozwijania projektu. Aby pobrać konfigurację lub wygenerować nowy token Git (reset tokenu), wywołaj GET/POST na adres endpointu konfiguracji projektu (confUrl): https://api.cobonaut.com/v1/projects/uuid-projektu/conf."
}
```

---

## 4. Pobieranie i zarządzanie konfiguracją projektu
Służy do pobierania konfiguracji istniejącego projektu oraz do resetowania/regenerowania tokenu dostępowego Git dla tego projektu.

### A. Pobranie konfiguracji (GET)
Zwraca aktualne metadane projektu. Jeśli projekt nie posiada jeszcze wygenerowanego tokenu Git (np. po migracji lub przy pierwszym wywołaniu), serwer automatycznie go wygeneruje i zwróci w odpowiedzi.

* **Metoda:** `GET`
* **URL:** `https://api.cobonaut.com/v1/projects/[projectId]/conf`

#### Przykład odpowiedzi (gdy token został wygenerowany):
```json
{
  "id": "uuid-projektu",
  "name": "Nowy Projekt",
  "templateKey": "nextjs-basic-app",
  "gitAccessToken": "ab12cd",
  "createdAt": "2026-06-12T16:00:00.000Z",
  "updatedAt": "2026-06-12T16:00:00.000Z",
  "repoUrl": "https://git.cobonaut.com/nazwa_uzytkownika/uuid-projektu.git",
  "authenticatedRepoUrl": "https://nazwa_uzytkownika:git_token_value@git.cobonaut.com/nazwa_uzytkownika/uuid-projektu.git",
  "settingsUrl": "https://cobonaut.com/workspace/uuid-projektu/settings",
  "workspaceUrl": "https://cobonaut.com/workspace/uuid-projektu",
  "instruction": "Utwórz w katalogu głównym projektu plik cobonaut.json i zapisz w nim konfigurację (projectId, gitToken, repoUrl itp.), aby nie utracić dostępu do Git.",
  "gitToken": "git_token_value"
}
```

### B. Resetowanie/Regenerowanie tokenu Git (POST)
Unieważnia stary token Git projektu i generuje nowy. Zwraca nowo wygenerowany token w polu `gitToken`.

* **Metoda:** `POST`
* **URL:** `https://api.cobonaut.com/v1/projects/[projectId]/conf`

#### Przykład odpowiedzi:
```json
{
  "id": "uuid-projektu",
  "name": "Nowy Projekt",
  "templateKey": "nextjs-basic-app",
  "gitAccessToken": "ef56gh",
  "createdAt": "2026-06-12T16:00:00.000Z",
  "updatedAt": "2026-06-12T16:00:00.000Z",
  "repoUrl": "https://git.cobonaut.com/nazwa_uzytkownika/uuid-projektu.git",
  "authenticatedRepoUrl": "https://nazwa_uzytkownika:new_git_token_value@git.cobonaut.com/nazwa_uzytkownika/uuid-projektu.git",
  "settingsUrl": "https://cobonaut.com/workspace/uuid-projektu/settings",
  "workspaceUrl": "https://cobonaut.com/workspace/uuid-projektu",
  "instruction": "Utwórz w katalogu głównym projektu plik cobonaut.json i zapisz w nim konfigurację (projectId, gitToken, repoUrl itp.), aby nie utracić dostępu do Git.",
  "gitToken": "new_git_token_value"
}
```

---

## 5. Inicjalizacja Nowego Wdrożenia (Pierwszy Deploy)
Tworzy i inicjalizuje pierwsze wdrożenie projektu (przypisuje unikalną nazwę i uruchamia kontener).

* **Metoda:** `POST`
* **URL:** `https://api.cobonaut.com/v1/deployments`
* **Content-Type:** `application/json`

### Parametry w body:
* `projectId` (string, wymagany) - ID projektu.
* `appName` (string, wymagany) - Unikalna nazwa subdomeny w domenie cloud.cobonaut.com.
* `serverSizeKey` (string, opcjonalny) - Rozmiar serwera (np. `free`, `eco`, `standard`). Domyślnie `free`.
* `type` (string, opcjonalny) - Typ środowiska wdrożenia. Dozwolone wartości: `prod`, `pre-prod`, `test`, `dev`. Domyślnie `dev`.
* `customDomain` (string, opcjonalny) - Domena własna do przypisania (np. `twojadomena.pl`).
* `buyDomainIfAvailable` (boolean, opcjonalny) - Czy automatycznie zarejestrować nową domenę w OVH (wymaga danych kontaktowych).
* `contact` (object, opcjonalny) - Dane kontaktowe abonenta do rejestracji domeny.

### Przykład odpowiedzi (Standardowa)
```json
{
  "success": true,
  "deployment": {
    "id": "uuid-wdrozenia",
    "projectId": "uuid-projektu",
    "appName": "moja-aplikacja",
    "status": "pending",
    "url": "https://moja-aplikacja.cloud.cobonaut.com",
    "serverSizeKey": "free"
  }
}
```

### Przykład odpowiedzi (Oczekiwanie na zakup nowej domeny)
```json
{
  "status": "AWAITING_CONFIRMATION",
  "actionId": "uuid-akcji",
  "deploymentId": "uuid-wdrozenia",
  "deploymentUrl": "https://moja-aplikacja.cloud.cobonaut.com",
  "instructionForUser": "Zleciłem wdrożenie projektu z zakupem domeny...",
  "message": "Wdrożenie startuje na domenie systemowej. Oczekiwanie na potwierdzenie zakupu domeny."
}
```

### Przykład odpowiedzi (Zewnętrzny rejestrator)
```json
{
  "id": "uuid-wdrozenia",
  "status": "AWAITING_DNS_CONFIGURATION",
  "dnsInstructions": {
    "message": "Skonfiguruj rekordy DNS u swojego rejestratora...",
    "records": [
      { "type": "A", "host": "@", "value": "51.83.162.89", "ttl": 3600 },
      { "type": "CNAME", "host": "www", "value": "twojadomena.pl", "ttl": 3600 }
    ],
    "verifyUrl": "/api/deployments/uuid-wdrozenia/custom-domain"
  }
}
```

---
 
## 6. Wywołanie wdrożenia / Aktualizacji (Redeploy)
Wywołuje procedurę aktualizacji kodu na serwerze.

* **Metoda:** `POST`
* **URL:** `https://api.cobonaut.com/v1/deploy`
* **Content-Type:** `application/json`
 
### Parametry w body:
* `appName` (string, opcjonalny/wymagany zamiennie z projectId) - Nazwa subdomeny aplikacji (np. "moja-aplikacja").
* `projectId` (string, opcjonalny/wymagany zamiennie z appName) - ID projektu.
* `commitSha` (string, opcjonalny) - SHA commitu do wdrożenia. W przypadku braku – pobiera najnowszy commit HEAD z gałęzi main repozytorium git.
* `update` (boolean, opcjonalny) - Wymusza pobranie i nadpisanie plików konfiguracyjnych oraz skryptów startowych z najnowszej wersji szablonu (np. Dockerfile, captain-definition, entrypoint-setup.sh). Pomocne przy aktualizacji starszych wdrożeń.
* `clean` (boolean, opcjonalny) - Wymusza wyczyszczenie bazy danych WordPressa (wywołanie `wp db reset`) i zainstalowanie go całkowicie od zera przy najbliższym uruchomieniu wdrożenia z użyciem nowej konfiguracji z pliku `wordpress.json`. **Ostrzeżenie**: Flaga ta jest całkowicie ignorowana, jeśli typ wdrożenia (środowisko) to `prod`.
 
### Przykład zapytania curl
```bash
curl -X POST https://api.cobonaut.com/v1/deploy \
  -H "Authorization: Bearer cobo_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "moja-aplikacja"
  }'
```
 
### Przykład odpowiedzi (HTTP 202 Accepted)
```json
{
  "message": "Rozpoczęto procedurę wdrożenia",
  "deploymentId": "uuid-wdrozenia",
  "appName": "moja-aplikacja",
  "status": "deploying",
  "commitSha": "4ca52ba47e668858f1be467d216738fd410b0123",
  "commitMessage": "chore: updates index page",
  "statusUrl": "https://api.cobonaut.com/v1/deployments/uuid-wdrozenia/status",
  "manageUrl": "https://cobonaut.com/cloud/uuid-wdrozenia",
  "instruction": "Po prawidłowym wdrożeniu poinformuj użytkownika, że pod tym linkiem może ręcznie zarządzać wdrożeniem z poziomu GUI: https://cobonaut.com/cloud/uuid-wdrozenia"
}
```
 
---
 
## 7. Sprawdzanie statusu wdrożenia
Zwraca aktualny stan budowania/działania kontenera.
 
* **Metoda:** `GET`
* **URL:** `https://api.cobonaut.com/v1/deployments/[deploymentId]/status`

### Przykład odpowiedzi
```json
{
  "success": true,
  "deploymentId": "uuid-wdrozenia",
  "appName": "moja-aplikacja",
  "status": "running",
  "commitSha": "4ca52ba47e668858f1be467d216738fd410b0123",
  "url": "https://moja-aplikacja.cloud.cobonaut.com"
}
```

---
 
## 8. Diagnostyka statusu serwera API (Healthcheck)
Publiczny endpoint diagnostyczny statusu serwera API.
 
* **Metoda:** `GET`
* **URL:** `https://api.cobonaut.com/v1/health`
 
---
 
## 9. Pobieranie profilu użytkownika
Zwraca podstawowe informacje o profilu zalogowanego użytkownika.

* **Metoda:** `GET`
* **URL:** `https://api.cobonaut.com/v1/me`

### Przykład odpowiedzi
```json
{
  "success": true,
  "user": {
    "id": "uuid-uzytkownika",
    "email": "user@example.com",
    "name": "Jan Kowalski",
    "isVerified": true,
    "apiEnabled": true
  },
  "instruction": "Dostęp do repozytorium git projektu jest przydzielany indywidualnie per-projekt w odpowiedzi z endpointu tworzenia projektu (POST /v1/projects) lub pobierania szczegółów konfiguracji projektu (GET /v1/projects/[id]/conf)."
}
```

---

## 10. Zmiana domeny wdrożenia
Zmienia domenę własną przypisaną do istniejącego wdrożenia.

* **Metoda:** `POST`
* **URL:** `https://api.cobonaut.com/v1/deployments/[deploymentId]/change-domain`
* **Content-Type:** `application/json`

### Parametry w body:
* `domain` (string, wymagany) - Nowa domena własna.
* `buyDomainIfAvailable` (boolean, opcjonalny) - Czy automatycznie zarejestrować nową domenę.
* `contact` (object, opcjonalny) - Dane kontaktowe abonenta.

---

## 11. Odpięcie domeny własnej
Odpina domenę własną od wdrożenia i przywraca domyślny URL systemowy (subdomenę *.cloud.cobonaut.com). Tworzy bezpłatne żądanie zatwierdzenia.

* **Metoda:** `POST`
* **URL:** `https://api.cobonaut.com/v1/deployments/[deploymentId]/detach-domain`
`


---
# Automation & AI Agents (Automatyzacja i Agenci AI)
ID: agent-flow

## English
# AI Agent & CLI Integration

This process allows developers utilizing terminal CLI or coding agents (such as Antigravity) to modify code locally, push it to Git, and remotely deploy it to production.

### 1. Clone the Git Repository
Fetch the project files locally from the Git server:
```bash
git clone https://git.cobonaut.com/user_cobonaut/[project-id].git
```

### 2. Modify & Push Changes
Make adjustments in your code (e.g. edit HTML/CSS). Create a commit and push to Git:
```bash
git add .
git commit -m "feat: updates hero section"
git push origin main
```

### 3. Trigger the Deployment via REST API
Call the dedicated REST API deploy endpoint on `api.cobonaut.com` with your API token to start building the container:
```http
POST https://api.cobonaut.com/v1/deploy
Authorization: Bearer cobo_live_[token]
Content-Type: application/json

{
  "appName": "my-app"
}
```

### 4. Track Build Status (Polling)
The CLI script or AI Agent periodically polls the status URL returned in the response under `statusUrl` (every 3-5s) until the build finishes:
```http
GET https://api.cobonaut.com/v1/deployments/[deployment-id]/status
Authorization: Bearer cobo_live_[token]
```

---

### 💡 Protip for AI Agents (Best Practice)
To prevent polluting the project workspace with temporary scripts and helper files used for API requests, we recommend building and reusing a local client SDK for communicating with Cobonaut.

1. **Build a "cobonautsdk"**: The agent should set up a shared client SDK / library (named `cobonautsdk`) designed to manage all communication with the Cobonaut API on the host machine.
2. **Persistent Configuration**: Store the API Token and settings in a centralized, secure location managed by `cobonautsdk` (e.g., in a global user configuration directory or environment variables), rather than prompting the user for credentials in every new project.
3. **Unified Interface**: Implement a single, stable interface or CLI mechanism within `cobonautsdk` to handle all API operations (registration, project creation, deployment, status), instead of generating raw HTTP request code blocks repeatedly across different workspaces.

This keeps the project workspace clean, avoids messy side-effects, and saves the agent's context window and execution time from rewriting basic API integration logic.

## Polish
# Integracja z Agentami AI i CLI

Zintegrowany proces pozwala programistom korzystającym z terminala oraz agentów AI (takich jak Antigravity) na modyfikowanie kodu lokalnie, wypychanie zmian bezpośrednio na git i zdalne wdrażanie ich na środowisko produkcyjne.

### 1. Klonowanie repozytorium git
Pobierz kod projektu lokalnie ze swojego serwera git:
```bash
git clone https://git.cobonaut.com/user_cobonaut/[project-id].git
```

### 2. Edycja i wypchnięcie zmian
Wprowadź poprawki w kodzie (np. dodaj nowy element UI). Następnie utwórz commit i zrób push do git:
```bash
git add .
git commit -m "feat: updates hero section"
git push origin main
```

### 3. Wywołanie API wdrożenia
Wywołaj dedykowany endpoint wdrożeń REST API na `api.cobonaut.com` przy użyciu swojego tokenu API, aby rozpocząć budowanie kontenera:
```http
POST https://api.cobonaut.com/v1/deploy
Authorization: Bearer cobo_live_[token]
Content-Type: application/json

{
  "appName": "tst-apka-nanan"
}
```

### 4. Odpytywanie o status (Polling)
Narzędzie CLI / Agent AI odpytuje cyklicznie URL statusu uzyskany z odpowiedzi `statusUrl` (co 3-5 sekund), aż do momentu ukończenia budowania kontenera:
```http
GET https://api.cobonaut.com/v1/deployments/[deployment-id]/status
Authorization: Bearer cobo_live_[token]
```

---

### 💡 Protip dla Agentów AI (Dobra praktyka)
Aby uniknąć zaśmiecania katalogu roboczego projektu jednorazowymi skryptami i plikami pomocniczymi do komunikacji z API, zaleca się stworzenie i reużywanie lokalnego klienta SDK do obsługi komunikacji z Cobonaut.

1. **Stworzenie "cobonautsdk"**: Agent powinien przygotować wspólny zestaw narzędzi lub bibliotekę kliencką (zalecana nazwa: `cobonautsdk`), którego celem jest realizacja całej komunikacji z API Cobonaut na maszynie klienta.
2. **Trwała konfiguracja**: Zapisuj i wczytuj Token API oraz konfigurację w centralnym, bezpiecznym miejscu powiązanym z `cobonautsdk` (np. w globalnym katalogu konfiguracyjnym użytkownika lub zmiennych środowiskowych), zamiast żądać ich wpisywania przy każdym projekcie.
3. **Ujednolicony interfejs**: Zaimplementuj w ramach `cobonautsdk` jeden wspólny, stabilny interfejs lub narzędzie CLI obsługujące wszystkie operacje API (rejestracja, tworzenie projektu, wdrożenie, status), zamiast generować ad-hoc kod zapytań HTTP dla każdego projektu od nowa.

Dzięki temu katalog roboczy projektu pozostanie czysty, a agent zaoszczędzi zasoby na ponowne generowanie logiki integracji i komunikacji z API.


---
# Agent-Driven Registration (Rejestracja przez Agenta AI)
ID: agent-registration

## English
# Agent-Driven Registration & Activation Flow

If a user doesn't have a Cobonaut account, an AI Agent can guide them through the registration and Stripe commercial verification flow directly:

### Scenario 1: Initial Setup and Registration

1. **Request Verification Code**:
   The agent calls the API endpoint `POST https://api.cobonaut.com/v1/register/request-code` passing user details:
   ```json
   {
     "email": "user@example.com"
   }
   ```
   The server pre-creates a pending user account, generates a 6-digit verification code (e.g. `823491`), a verification token (UUID) for the email link, and a **dedicated agent session token** (`agentSessionToken`) for automatic polling.

   **Response:**
   ```json
   {
     "success": true,
     "message": "Verification code sent to email",
     "code": "823491",
     "email": "user@example.com",
     "agentSessionToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "statusPollingUrl": "https://api.cobonaut.com/v1/register/status?email=user%40example.com&agentSessionToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "instruction": {
       "instructionForUser": "Registration initiated. Check your email (user@example.com) and click the verification link. Enter code: 823491 on the page. After verification you will be redirected to Stripe payment.",
       "nextAction": {
         "method": "GET",
         "url": "https://api.cobonaut.com/v1/register/status?email=user%40example.com&agentSessionToken=xxxxxxxx-...",
         "description": "Poll this endpoint every 10 seconds (max 15 min). When status changes to 'active', the response will contain apiToken field.",
         "pollingIntervalSeconds": 10,
         "maxPollingDurationSeconds": 900,
         "expectedResponses": {
           "pending": { "status": "pending_payment", "description": "User hasn't paid yet. Continue polling." },
           "success": { "status": "active", "description": "Account active. apiToken field contains the API token." },
           "expired": { "status": 400, "description": "Agent session token expired (15 min). Re-initiate registration." }
         }
       },
       "fallbackNote": "If automatic retrieval fails, ask the user to save the token in a .cob file."
     }
   }
   ```
   > **Important:** The agent must store the `agentSessionToken` (or use the ready-made `statusPollingUrl`) — it is a one-time, short-lived token (valid for 15 minutes) used exclusively for polling registration status and automatically retrieving the API token. The agent does **not** receive the email verification token — it cannot confirm registration on its own.

2. **Display Instructions**:
   The agent outputs the following instruction to the user console:
   > Registration initiated. Please check your email and click the Cobonaut verification link.
   > On the opened page, enter the following verification code:
   > **XXXXXX**

3. **Verify and Pay**:
   The user opens the email link, enters the code provided by the Agent, and submits. The page redirects the user to Stripe Checkout to complete the verification payment.

4. **Automatic Status Polling & API Token Retrieval**:
   The agent periodically polls the status endpoint (e.g., every 10 seconds, max 15 minutes) using its `agentSessionToken`:
   ```http
   GET https://api.cobonaut.com/v1/register/status?email=user@example.com&agentSessionToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   ```
   **Response before payment:**
   ```json
   {
     "email": "user@example.com",
     "status": "pending_payment",
     "isVerified": false,
     "apiEnabled": false
   }
   ```
   **Response after payment (one-time API token retrieval):**
   ```json
   {
     "email": "user@example.com",
     "status": "active",
     "isVerified": true,
     "apiEnabled": true,
     "apiToken": "cobo_live_XXXXXXXXXXXXX"
   }
   ```
   > **Note:** After successfully retrieving the API token, the session record is immediately deleted — the `agentSessionToken` becomes invalid. The API token can only be retrieved via this method **once**.

5. **Save API Token & Resume Work**:
   The agent saves the received `apiToken` in its configuration file (e.g. `cobonaut.json` or `cobonautsdk` config) and immediately resumes work.

   **Manual Fallback (if automatic retrieval fails):** The user will see the API token on the payment confirmation screen with instructions: create a `.cob` file with the key and mention it to the agent, or paste it in the console prompt (not recommended).

6. **Create Project & Git Clone**:
   The agent calls `POST https://api.cobonaut.com/v1/projects` using the new API Token. The server provisions the project and returns a Git-authenticated URL:
   ```http
   https://git-user:git-token-xyz@git.cobonaut.com/username/uuid-project.git
   ```
   The agent clones this URL locally, modifies the files, and pushes them back seamlessly.

## Polish
# Rejestracja i Aktywacja Konta przez Agenta AI

Jeśli użytkownik nie posiada jeszcze konta w Cobonaut, Agent AI może przeprowadzić go przez proces rejestracji oraz weryfikacji płatności bez użycia pełnego interfejsu graficznego:

### Scenariusz 1: Pierwsze uruchomienie projektu i rejestracja

1. **Inicjalizacja rejestracji**:
   Agent wywołuje endpoint API `POST https://api.cobonaut.com/v1/register/request-code` przesyłając dane użytkownika:
   ```json
   {
     "email": "user@example.com"
   }
   ```
   Serwer pre-tworzy konto w bazie w statusie pending, generuje 6-cyfrowy kod weryfikacyjny (np. `823491`), generuje token weryfikacyjny (UUID) do linku e-mail oraz **dedykowany token sesji agenta** (`agentSessionToken`) do automatycznego pollingu.

   **Odpowiedź:**
   ```json
   {
     "success": true,
     "message": "Verification code sent to email",
     "code": "823491",
     "email": "user@example.com",
     "agentSessionToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "statusPollingUrl": "https://api.cobonaut.com/v1/register/status?email=user%40example.com&agentSessionToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "instruction": {
       "instructionForUser": "Rejestracja konta Cobonaut została zainicjowana. Sprawdź skrzynkę e-mail (user@example.com) i kliknij link weryfikacyjny. Na stronie wpisz kod: 823491. Po weryfikacji zostaniesz przekierowany do płatności Stripe.",
       "nextAction": {
         "method": "GET",
         "url": "https://api.cobonaut.com/v1/register/status?email=user%40example.com&agentSessionToken=xxxxxxxx-...",
         "description": "Odpytuj ten endpoint co 10 sekund (max 15 min). Gdy status zmieni się na 'active', odpowiedź będzie zawierała pole apiToken.",
         "pollingIntervalSeconds": 10,
         "maxPollingDurationSeconds": 900,
         "expectedResponses": {
           "pending": { "status": "pending_payment", "description": "Użytkownik jeszcze nie opłacił konta. Kontynuuj polling." },
           "success": { "status": "active", "description": "Konto aktywne. Pole apiToken zawiera token API." },
           "expired": { "status": 400, "description": "Token sesji agenta wygasł (15 min). Zainicjuj rejestrację ponownie." }
         }
       },
       "fallbackNote": "Jeśli automatyczne pobranie tokenu nie zadziała, poproś użytkownika o zapisanie tokenu w pliku .cob."
     }
   }
   ```
   > **Ważne:** Agent musi zapamiętać `agentSessionToken` (lub użyć gotowego `statusPollingUrl`) — jest to jednorazowy, krótkotrwały token (ważny 15 minut) służący wyłącznie do odpytywania statusu rejestracji i automatycznego pobrania tokenu API. Agent **nie** otrzymuje tokenu weryfikacyjnego z e-maila — nie może samodzielnie potwierdzić rejestracji.

2. **Wyświetlenie instrukcji użytkownikowi**:
   Agent wyświetla w konsoli komunikat:
   > Rejestracja rozpoczęta. Sprawdź swoją skrzynkę e-mail i kliknij w link weryfikacyjny Cobonaut.
   > Po otwarciu strony wpisz poniższy kod weryfikacyjny:
   > **XXXXXX**

3. **Weryfikacja i płatność**:
   Użytkownik klika w link z e-maila, wpisuje kod podany przez Agenta na stronie i klika "Potwierdź". Strona przekierowuje użytkownika do Stripe Checkout, aby sfinalizować rejestrację płatnością.

4. **Automatyczne odpytywanie o status i pobranie tokenu API (Polling)**:
   Agent cyklicznie odpytuje endpoint statusu (np. co 10 sekund, max 15 minut) podając swój `agentSessionToken`:
   ```http
   GET https://api.cobonaut.com/v1/register/status?email=user@example.com&agentSessionToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   ```
   **Odpowiedź przed opłaceniem:**
   ```json
   {
     "email": "user@example.com",
     "status": "pending_payment",
     "isVerified": false,
     "apiEnabled": false
   }
   ```
   **Odpowiedź po opłaceniu (jednorazowe pobranie tokenu API):**
   ```json
   {
     "email": "user@example.com",
     "status": "active",
     "isVerified": true,
     "apiEnabled": true,
     "apiToken": "cobo_live_XXXXXXXXXXXXX"
   }
   ```
   > **Uwaga:** Po pomyślnym pobraniu tokenu API, rekord sesji zostaje natychmiast usunięty z bazy — `agentSessionToken` traci ważność. Token API można pobrać tą metodą **tylko raz**.

5. **Zapisanie tokenu API i wznowienie pracy**:
   Agent zapisuje otrzymany `apiToken` w swoim pliku konfiguracyjnym (np. `cobonaut.json` lub konfiguracji `cobonautsdk`) i od razu kontynuuje pracę.

   **Fallback (jeśli automatyczne pobieranie nie zadziała):** Użytkownik zobaczy token API na ekranie potwierdzenia płatności z instrukcją: utworzenie pliku `.cob` z kluczem i przekazanie go agentowi, lub wklejenie w konsoli prompt (metoda nierekomendowana).

6. **Tworzenie projektu z autoryzacją Git**:
   Agent wywołuje `POST https://api.cobonaut.com/v1/projects` za pomocą nowego Tokenu API. Serwer tworzy projekt i zwraca uwierzytelniony adres URL repozytorium:
   ```http
   https://git-user:git-token-xyz@git.cobonaut.com/git-user/project-id.git
   ```
   Agent klonuje to repozytorium lokalnie, wprowadza poprawki i robi `git push` bez monitów o hasło.