# Guru Core Agent API

Guru Core exists to let an agent self-publish code to hosted applications through a controlled API.

At MVP stage:

- humans use the UI to create and manage workspaces
- each workspace gets one mailbox identity
- the agent receives an API key for that workspace
- the agent can create and manage applications
- the agent can publish content into those applications through the API
- the mailbox gives the agent an email identity for human communication

## Product rules

- A workspace is the agent's home
- Applications belong to a workspace
- App hostnames always include the workspace slug:
  - `<app-slug>.<workspace-slug>.a.guru-core.net`
- Free plan:
  - 1 workspace
  - 1 application
- Static and PHP apps are the default API-first publish targets
- Node.js and Python hosted runtimes are available on paid plans
- Site/server state should be managed through Guru Core provisioning, not by ad hoc shell changes
- Content deployment inside the application webroot is handled through the Guru Core API

## Base URL

Production base URL:

```text
https://guru-core.net
```

API root:

```text
https://guru-core.net/api/
```

## Authentication

Use a workspace bearer token.

```http
Authorization: Bearer gct_...
```

Tokens are workspace-scoped.

Current token scopes in the system:

- `workspace:read`
- `workspace:write`
- `apps:read`
- `apps:write`
- `files:read`
- `files:write`
- `deploy`
- `delete`

## Core flow for an agent

1. Receive workspace API key from the human
2. Read workspace details and mailbox settings
3. List or create applications
4. Publish files into an application
5. Rotate mailbox password if mailbox access is needed

## Endpoints

### 1. API index

`GET /api/`

Returns workspace summary, applications, and route hints.

Example:

```bash
curl -sS https://guru-core.net/api/ \
  -H 'Authorization: Bearer gct_xxx'
```

### 2. Workspace details

`GET /api/workspace.php`

Returns:

- workspace summary
- application count
- token hint
- active token id
- mailbox settings
- recent jobs

Example:

```bash
curl -sS https://guru-core.net/api/workspace.php \
  -H 'Authorization: Bearer gct_xxx'
```

Typical mailbox block:

```json
{
  "mailbox": {
    "address": "ops@workspace.a.guru-core.net",
    "status": "active",
    "imap": {
      "host": "fe1-ionos.inboxsy.io",
      "port": 993,
      "security": "ssl/tls"
    },
    "smtp": {
      "host": "fe1-ionos.inboxsy.io",
      "port": 587,
      "security": "starttls"
    },
    "username": "ops@workspace.a.guru-core.net",
    "password_status": "not_retrievable_use_rotate"
  }
}
```

### 3. Rotate mailbox password

`POST /api/workspace.php`

Body:

```json
{
  "action": "rotate_mailbox_password"
}
```

This returns a newly generated mailbox password once.

Example:

```bash
curl -sS -X POST https://guru-core.net/api/workspace.php \
  -H 'Authorization: Bearer gct_xxx' \
  -H 'Content-Type: application/json' \
  --data '{"action":"rotate_mailbox_password"}'
```

### 4. List applications

`GET /api/applications.php`

Example:

```bash
curl -sS https://guru-core.net/api/applications.php \
  -H 'Authorization: Bearer gct_xxx'
```

### 5. Create application

`POST /api/applications.php`

Body:

```json
{
  "name": "Portal",
  "app_type": "static"
}
```

Supported MVP app types:

- `static`
- `php`

Example:

```bash
curl -sS -X POST https://guru-core.net/api/applications.php \
  -H 'Authorization: Bearer gct_xxx' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Portal","app_type":"static"}'
```

### 6. Get application

`GET /api/application.php?id={application_id}`

Returns app summary plus file API support info.

### 7. Rename application

`PATCH /api/application.php?id={application_id}`

or `POST` with JSON body:

```json
{
  "name": "New name"
}
```

### 8. Delete application

`DELETE /api/application.php?id={application_id}`

Queues application deletion.

### 9. List directory or read file

`GET /api/files.php?application_id={application_id}&path={relative_path}`

Rules:

- empty `path` lists the app webroot
- directory path returns a directory object
- file path returns a file object
- API responses use logical relative paths only

Example directory listing:

```bash
curl -sS 'https://guru-core.net/api/files.php?application_id=14' \
  -H 'Authorization: Bearer gct_xxx'
```

Example file read:

```bash
curl -sS 'https://guru-core.net/api/files.php?application_id=14&path=index.html' \
  -H 'Authorization: Bearer gct_xxx'
```

### 10. Write one file

`PUT /api/files.php?application_id={application_id}&path={relative_path}`

Plain text body:

```bash
curl -sS -X PUT \
  'https://guru-core.net/api/files.php?application_id=14&path=index.html' \
  -H 'Authorization: Bearer gct_xxx' \
  -H 'Content-Type: text/html' \
  --data '<!doctype html><html><body>Hello</body></html>'
```

Or JSON body:

```json
{
  "content": "SGVsbG8=",
  "encoding": "base64"
}
```

### 11. Create directory

`POST /api/files.php?application_id={application_id}`

Body:

```json
{
  "action": "mkdir",
  "path": "assets"
}
```

### 12. Delete file or directory

`DELETE /api/files.php?application_id={application_id}&path={relative_path}`

### 13. Batch deploy

`POST /api/deploy.php?application_id={application_id}`

Body:

```json
{
  "replace": false,
  "ops": [
    {
      "action": "write",
      "path": "index.html",
      "content": "<!doctype html><html><body><h1>Hello</h1></body></html>"
    },
    {
      "action": "mkdir",
      "path": "assets"
    },
    {
      "action": "write",
      "path": "assets/status.txt",
      "content": "ok"
    }
  ]
}
```

Use this as the default publish path for agents.

## Deployment model

For static/PHP apps, agents should prefer batch deploy over many one-off file writes.

Recommended publish sequence:

1. `GET /api/workspace.php`
2. `GET /api/applications.php`
3. create app if needed
4. `POST /api/deploy.php?application_id=...`
5. optionally verify with file reads or live host fetch

## Mailbox access model

Mailbox details are workspace-level, not app-level.

Use:

- IMAP host: `fe1-ionos.inboxsy.io`
- IMAP port: `993`
- IMAP security: `ssl/tls`
- SMTP host: `fe1-ionos.inboxsy.io`
- SMTP port: `587`
- SMTP security: `starttls`
- username: workspace mailbox address

Mailbox passwords are not retrievable after creation.
If an agent needs mailbox access, rotate the password and store the new one securely.

## Security and limits

Current protections:

- workspace-scoped bearer token auth
- scoped token checks
- payload size limits
- batch op count limits
- audit logging
- path traversal protection
- reserved directory mutation blocked for top-level paths like:
  - `error`
  - `stats`
  - `cgi-bin`
  - `ssl`
  - `private`
  - `log`
  - `tmp`
  - `webdav`
- internal filesystem paths are not returned in normal API summaries

Important constraint:

- Site/server state is not for agents to mutate directly
- DNS, web server config, SSL, PHP mode, and mailbox provisioning are controlled through Guru Core provisioning
- agent content deployment is limited to the application webroot

## Suggested agent prompt snippet

```text
You are deploying to Guru Core.
Use the provided workspace bearer token.
First inspect the workspace and mailbox settings, then list or create applications, then publish static/PHP files using the batch deploy endpoint.
Do not assume server paths.
Do not attempt to modify DNS, SSL, web server, or mail infrastructure directly.
If mailbox access is needed, rotate the mailbox password through the workspace API and store the returned password securely.
```

## MVP status

At this stage, Guru Core is intended to support:

- human-created workspaces
- one mailbox per workspace
- agent self-publishing into static/PHP apps through API
- free tier with one workspace and one app

This document should be kept aligned with the live API behaviour.