# Cobonaut REST API Reference

---
# 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 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"
    }
  ]
}
```

---

## 2. Create Project
Creates a new project and seeds its Git repository from the selected template. Also returns the Gitea 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
{
  "success": true,
  "project": {
    "id": "uuid-project",
    "name": "New Project",
    "templateKey": "nextjs-basic-app",
    "createdAt": "2026-06-12T16:00:00.000Z",
    "updatedAt": "2026-06-12T16:00:00.000Z"
  },
  "repoUrl": "https://git.cobonaut.com/username/uuid-project.git"
}
```

---

## 3. Trigger Deployment (Deploy)
Triggers the code update and build procedure on the CapRover 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 CapRover 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 Gitea repository main branch.

### 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": "Rozpoczęto procedurę wdrożenia",
  "deploymentId": "uuid-deployment",
  "appName": "my-app",
  "status": "deploying",
  "commitSha": "4ca52ba47e668858f1be467d216738fd410b0123",
  "commitMessage": "chore: updates index page",
  "statusUrl": "https://cobonaut.com/api/deployments/uuid-deployment/status"
}
```

---

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

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

## 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 (np. Antigravity) oraz skryptami.

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

---

## 1. 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"
    }
  ]
}
```

---

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

* **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
{
  "success": true,
  "project": {
    "id": "uuid-projektu",
    "name": "Nowy Projekt",
    "templateKey": "nextjs-basic-app",
    "createdAt": "2026-06-12T16:00:00.000Z",
    "updatedAt": "2026-06-12T16:00:00.000Z"
  },
  "repoUrl": "https://git.cobonaut.com/nazwa_uzytkownika/uuid-projektu.git"
}
```

---

## 3. Wywołanie wdrożenia (Deploy)
Wywołuje procedurę aktualizacji kodu na serwerze CapRover.

* **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 Gitea.

### 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://cobonaut.com/api/deployments/uuid-wdrozenia/status"
}
```

---

## 4. Diagnostyka statusu serwera API (Healthcheck)
Publiczny endpoint diagnostyczny statusu serwera API.

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


---
# 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 (like Antigravity) to modify code locally, push it to Gitea, and remotely deploy it to production.

### 1. Clone the Gitea Repository
Fetch the project files locally from the Gitea 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 Gitea:
```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": "tst-apka-nanan"
}
```

### 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://cobonaut.com/api/deployments/[deployment-id]/status
```

## 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 Gitea i zdalne wdrażanie ich na środowisko produkcyjne.

### 1. Klonowanie repozytorium Gitea
Pobierz kod projektu lokalnie ze swojego serwera Gitea:
```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 Gitea:
```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://cobonaut.com/api/deployments/[deployment-id]/status
```