> ## Documentation Index
> Fetch the complete documentation index at: https://how.to.usegolem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Apps API

> Create, verify, and manage apps programmatically

# Apps API

## List your apps

`GET /api/apps`

```bash theme={null}
curl -H "Authorization: Bearer $GOLEM_API_KEY" \
  https://api.usegolem.ai/api/apps
```

Returns every app you own with its domain, verification status, plan, credits, and security focus.

## Create an app

`POST /api/apps`

```bash theme={null}
curl -X POST https://api.usegolem.ai/api/apps \
  -H "Authorization: Bearer $GOLEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Production", "domain": "acme.example.com"}'
```

| Field        | Required | Notes                                  |
| ------------ | -------- | -------------------------------------- |
| `name`       | yes      | 1–100 characters                       |
| `domain`     | yes      | Valid domain, normalized automatically |
| `subdomains` | no       | Additional in-scope subdomains         |

## Create a draft (with verification)

The draft flow is the recommended path for new targets: create a draft, prove ownership, finalize.

`POST /api/app-drafts`

```bash theme={null}
curl -X POST https://api.usegolem.ai/api/app-drafts \
  -H "Authorization: Bearer $GOLEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production",
    "domain": "acme.example.com",
    "appType": "web",
    "securityFocus": ["data-theft", "admin-takeover"]
  }'
```

The response includes a **verification token**. Prove ownership by either:

* Adding `<meta name="golem-verify" content="<token>">` to the site's HTML head, or
* Adding a DNS TXT record at `_golem-verify.<domain>` with value `golem-verify=<token>`

Then verify:

`POST /api/app-drafts/{id}/verify`

On success the draft is finalized into an app, and subdomain + tech-stack scans start automatically.

For mobile apps, pass `appType: "mobile"` with `mobilePlatform` (`ios` / `android`) and `mobileIdentifier` (bundle ID / package name). Mobile drafts require an attestation at verify time.

## Manage an app

| Endpoint                              | Purpose                                          |
| ------------------------------------- | ------------------------------------------------ |
| `GET /api/apps/{id}`                  | Full app details                                 |
| `PATCH /api/apps/{id}`                | Update name, domain, subdomains, security focus  |
| `DELETE /api/apps/{id}`               | Soft-delete the app and its history              |
| `POST /api/apps/{id}/verify`          | Verification status and re-check                 |
| `POST /api/apps/{id}/accept-terms`    | Record the signed authorized-testing attestation |
| `GET /api/apps/{id}/assets`           | Discovered subdomains and their metadata         |
| `POST /api/apps/{id}/tech-stack-scan` | Trigger a tech-stack scan                        |

## Security focus

Accepted on app creation, app update, and per-audit. Up to 8 keys per app/run:

`data-theft`, `admin-takeover`, `data-tampering`, `malicious-uploads`, `payment-abuse`, `business-disruption`, `data-exposure`, `integration-abuse`, `account-takeover`, `general-security`

Pass `[]` to clear. See [Security focus](/audits/overview#security-focus) for what each directs the agent toward.

## Billing per app

| Endpoint                                | Purpose                          |
| --------------------------------------- | -------------------------------- |
| `GET /api/apps/{id}/billing`            | Plan, credit balance, reset date |
| `POST /api/apps/{id}/billing/subscribe` | Change plan                      |
| `POST /api/apps/{id}/billing/recharge`  | Purchase credits                 |
| `GET /api/apps/{id}/billing/portal`     | Stripe billing portal session    |

## Scheduled audits

| Endpoint                                                        | Purpose                                                                  |
| --------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `GET /api/apps/{id}/scheduled-audits`                           | List schedules                                                           |
| `POST /api/apps/{id}/scheduled-audits`                          | Create (`auditType`: shallow/deep, `cronExpression`, optional `targets`) |
| `GET/PATCH/DELETE /api/apps/{id}/scheduled-audits/{scheduleId}` | Manage one schedule                                                      |

## Error reference

| Error                       | Meaning                                             |
| --------------------------- | --------------------------------------------------- |
| `App not found`             | The app ID doesn't exist or belongs to another user |
| `Invalid domain`            | Domain failed validation                            |
| `Targets out of scope: ...` | A target isn't within the app's verified scope      |
| `Insufficient credits`      | The app's balance can't cover the audit             |