### Install here.now Skill

Source: https://here.now/docs

Installs the here.now skill for agent integration. Use the -g flag for global installation.

```bash
npx skills add heredotnow/skill --skill here-now -g
```

--------------------------------

### Fallback Install here.now Skill

Source: https://here.now/docs

A fallback method to install the here.now skill using a curl script.

```bash
curl -fsSL https://here.now/install.sh | bash
```

--------------------------------

### Create Subdomain Handle Response

Source: https://here.now/docs

Example response after successfully creating a subdomain handle.

```json
{ "handle": "yourname", "hostname": "yourname.here.now" }
```

--------------------------------

### Authenticated Site Creation Response

Source: https://here.now/docs

This is an example of the response when creating a site with authentication. It includes upload details and finalize URL.

```json
{
  "slug": "bright-canvas-a7k2",
  "siteUrl": "https://bright-canvas-a7k2.here.now/",
  "displayName": "My site",
  "displayDescription": "A short summary shown in your dashboard and search results.",
  "upload": {
    "versionId": "01J...",
    "uploads": [
      {
        "path": "index.html",
        "method": "PUT",
        "url": "https://<presigned-url>",
        "headers": { "Content-Type": "text/html; charset=utf-8" }
      }
    ],
    "skipped": ["assets/app.js"],
    "finalizeUrl": "https://here.now/api/v1/publish/bright-canvas-a7k2/finalize",
    "expiresInSeconds": 3600
  }
}
```

--------------------------------

### API Key Creation Response

Source: https://here.now/docs

This is an example of the JSON response received after successfully creating an API key.

```json
{
  "id": "9f4e...",
  "name": "claude",
  "key": "hnk_<64 hex chars>",
  "keySuffix": "a1b2",
  "createdAt": "2026-06-11T00:00:00.000Z"
}
```

--------------------------------

### PATCH Access API Response Example

Source: https://here.now/docs

Example response after patching the access policy, showing the updated access details and notification status.

```json
{
  "access": {
    "mode": "restricted",
    "accessPolicyVersion": 4,
    "allowedEmails": ["person@example.com"],
    "allowedDomains": ["example.com"]
  },
  "notifications": {
    "sent": ["person@example.com"],
    "failed": [],
    "skipped": []
  }
}
```

--------------------------------

### Invite Specific Email and Domain Access

Source: https://here.now/docs

This example shows how to invite a specific email address and allow access from a specific domain. It's recommended to read the current policy first to preserve existing entries before applying changes via PATCH.

```bash
# 1. Read the current policy.
curl -sS https://here.now/api/v1/publish/bright-canvas-a7k2/access \
  -H "Authorization: Bearer $HERENOW_API_KEY"

# 2. Write the complete merged list.
curl -sS https://here.now/api/v1/publish/bright-canvas-a7k2/access \
  -X PATCH \
  -H "Authorization: Bearer $HERENOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "mode": "restricted", \
    "allowedEmails": ["existing@example.com", "person@example.com"], \
    "allowedDomains": ["example.com"], \
    "notify": false \
  }'
```

--------------------------------

### Collection manifest configuration

Source: https://here.now/docs

Example JSON manifest for configuring a 'todos' collection with specific fields, access rules, and public mutation settings.

```json
{
  "collections": {
    "todos": {
      "fields": {
        "text": { "type": "string", "required": true, "maxLength": 200 },
        "done": { "type": "boolean", "default": false }
      },
      "access": {
        "read": "public",
        "insert": "public",
        "update": "public",
        "delete": "owner"
      },
      "publicMutation": "open"
    }
  }
}
```

--------------------------------

### Site Analytics Response Example

Source: https://here.now/docs

Example JSON response for site analytics, detailing views, visitors, top paths, referrers, countries, crawlers, and 404 paths.

```json
{
  "slug": "bright-canvas-a7k2",
  "range": "30d",
  "analyticsStartedAt": "2026-05-22T00:00:00.000Z",
  "lastEventAt": "2026-05-26T18:32:14.000Z",
  "totals": {
    "allTimeViews": 1240,
    "rangeViews": 312,
    "rangeVisitors": 201
  },
  "series": [
    { "bucket": "2026-05-26", "views": 42, "visitors": 31 }
  ],
  "topPaths": [
    { "path": "/", "views": 140 }
  ],
  "topReferrers": [
    { "referrer": "Direct", "views": 88 }
  ],
  "topCountries": [
    { "country": "US", "views": 120 }
  ],
  "topCrawlers": [
    { "crawler": "GPTBot", "hits": 18 }
  ],
  "top404Paths": [
    { "path": "/old-page", "referrer": "Direct", "hits": 12 }
  ]
}
```

--------------------------------

### Get site details

Source: https://here.now/docs

Retrieves metadata and the file manifest for a specific site's live version. Supports an alias for artifacts.

```APIDOC
## Get site details

### Description
Returns metadata and the full file manifest for the current live version of a site. Requires owner authorization.

### Method
GET

### Endpoint
GET /api/v1/publish/:slug (alias: GET /api/v1/artifact/:slug)

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique identifier of the site.

#### Query Parameters
- **Authorization** (string) - Required - Bearer <API_KEY> (owner only)

### Response
#### Success Response (200)
- **slug** (string) - The unique identifier for the site.
- **siteUrl** (string) - The live URL of the site.
- **status** (string) - The current status of the site.
- **createdAt** (string) - The timestamp when the site was created.
- **updatedAt** (string) - The timestamp when the site was last updated.
- **expiresAt** (null) - The expiration timestamp for the site (if applicable).
- **currentVersionId** (string) - The ID of the current live version.
- **pendingVersionId** (null) - The ID of any pending version (if applicable).
- **displayName** (string) - Owner-facing display name for the site.
- **displayDescription** (string) - Owner-facing display description for the site.
- **metadata** (object) - Repeats effective display values with their source.
  - **displayName** (string) - The display name.
  - **displayDescription** (string) - The display description.
  - **displayNameSource** (string) - The source of the display name.
  - **displayDescriptionSource** (string) - The source of the display description.
- **manifest** (array) - Lists all files in the current version.
  - **path** (string) - The path of the file.
  - **size** (integer) - The size of the file in bytes.
  - **contentType** (string) - The MIME type of the file.
  - **hash** (string) - The hash of the file content.

### Response Example
```json
{
  "slug": "bright-canvas-a7k2",
  "siteUrl": "https://bright-canvas-a7k2.here.now/",
  "status": "active",
  "createdAt": "2026-02-18T...",
  "updatedAt": "2026-02-18T...",
  "expiresAt": null,
  "currentVersionId": "01J...",
  "pendingVersionId": null,
  "displayName": "Bright Canvas",
  "displayDescription": "A small static site with generated artwork and notes.",
  "metadata": {
    "displayName": "Bright Canvas",
    "displayDescription": "A small static site with generated artwork and notes.",
    "displayNameSource": "caller",
    "displayDescriptionSource": "content_generated"
  },
  "manifest": [
    { "path": "index.html", "size": 1234, "contentType": "text/html; charset=utf-8", "hash": "a1b2c3d4..." },
    { "path": "assets/app.js", "size": 999, "contentType": "text/javascript; charset=utf-8", "hash": "e5f6a7b8..." }
  ]
}
```
```

--------------------------------

### Account Analytics Response Example

Source: https://here.now/docs

Example JSON response for account-level analytics, including aggregated views, visitors, asset hits, not found hits, bot hits, and top sites.

```json
{
  "range": "30d",
  "analyticsStartedAt": "2026-05-22T00:00:00.000Z",
  "lastEventAt": "2026-05-26T18:32:14.000Z",
  "totals": {
    "allTimeViews": 8420,
    "rangeViews": 1204,
    "rangeVisitors": 822,
    "assetHits": 330,
    "notFoundHits": 18,
    "botHits": 91
  },
  "series": [
    { "bucket": "2026-05-26", "views": 120, "visitors": 84 }
  ],
  "topSites": [
    { "slug": "bright-canvas-a7k2", "views": 312, "visitors": 201 }
  ],
  "topReferrers": [
    { "referrer": "Direct", "views": 420 }
  ],
  "topCountries": [
    { "country": "US", "views": 510 }
  ],
  "topCrawlers": [
    { "crawler": "GPTBot", "hits": 91 }
  ],
  "top404Paths": [
    { "slug": "bright-canvas-a7k2", "path": "/old-page", "hits": 12 }
  ]
}
```

--------------------------------

### Get Profile Settings API Request

Source: https://here.now/docs

Retrieve the current public profile settings for your account using this GET request. Requires a valid API key.

```bash
curl -sS https://here.now/api/v1/profile \
  -H "Authorization: Bearer <API_KEY>"
```

--------------------------------

### Profile API Error Response Example

Source: https://here.now/docs

Example of a typical error response from the Profile API, including human-readable and machine-readable error codes.

```json
{
  "error": "This username is unavailable.",
  "code": "username_unavailable",
  "message": "This username is unavailable."
}
```

--------------------------------

### Get Site Details API Response

Source: https://here.now/docs

Response from the GET /api/v1/publish/:slug endpoint, providing metadata and the file manifest for a specific site. Requires owner authentication.

```json
{
  "slug": "bright-canvas-a7k2",
  "siteUrl": "https://bright-canvas-a7k2.here.now/",
  "status": "active",
  "createdAt": "2026-02-18T...",
  "updatedAt": "2026-02-18T...",
  "expiresAt": null,
  "currentVersionId": "01J...",
  "pendingVersionId": null,
  "displayName": "Bright Canvas",
  "displayDescription": "A small static site with generated artwork and notes.",
  "metadata": {
    "displayName": "Bright Canvas",
    "displayDescription": "A small static site with generated artwork and notes.",
    "displayNameSource": "caller",
    "displayDescriptionSource": "content_generated"
  },
  "manifest": [
    { "path": "index.html", "size": 1234, "contentType": "text/html; charset=utf-8", "hash": "a1b2c3d4..." },
    { "path": "assets/app.js", "size": 999, "contentType": "text/javascript; charset=utf-8", "hash": "e5f6a7b8..." }
  ]
}
```

--------------------------------

### List Sites on Profile API Request

Source: https://here.now/docs

Fetch a list of all Sites currently displayed on your public profile using this GET request. Requires a valid API key.

```bash
curl -sS https://here.now/api/v1/profile/sites \
  -H "Authorization: Bearer <API_KEY>"
```

--------------------------------

### Get Default Drive

Source: https://here.now/docs

Retrieves the account's default Drive. If it doesn't exist, it will be created (e.g., 'My Drive'). Requires Authorization header.

```APIDOC
## GET /api/v1/drives/default

### Description
Gets the account default Drive, lazily creating 'My Drive' if needed.

### Method
GET

### Endpoint
/api/v1/drives/default

### Request Headers
- Authorization: Bearer <API_KEY> or Drive token
```

--------------------------------

### Get Profile Settings

Source: https://here.now/docs

Retrieves the current profile settings, including whether the public profile is enabled and if new sites are automatically added to the profile.

```APIDOC
## Get Profile Settings

### Description
Retrieves the current profile settings, including whether the public profile is enabled and if new sites are automatically added to the profile.

### Method
GET

### Endpoint
/api/v1/profile

### Response
#### Success Response (200)
- **enabled** (boolean) - Indicates if the public profile is currently enabled.
- **addNewSitesToProfile** (boolean) - Indicates if new sites are automatically added to the profile.
```

--------------------------------

### List Sites API Response

Source: https://here.now/docs

Response from the GET /api/v1/publishes endpoint, showing a list of sites owned by the authenticated user. Requires an API key in the Authorization header.

```json
{
  "publishes": [
    {
      "slug": "bright-canvas-a7k2",
      "siteUrl": "https://bright-canvas-a7k2.here.now/",
      "updatedAt": "2026-02-18T...",
      "expiresAt": null,
      "status": "active",
      "currentVersionId": "01J...",
      "pendingVersionId": null
    }
  ]
}
```

--------------------------------

### Create Site with here.now API

Source: https://here.now/docs

Initiates the site publishing process by creating a site entry. This step returns upload URLs and a finalize URL. Anonymous sites expire in 24 hours.

```bash
curl -sS https://here.now/api/v1/publish \
  -H "X-HereNow-Client: cursor/direct-api" \
  -H "content-type: application/json" \
  -d '{
    "files": [
      { "path": "index.html", "size": 1234, "contentType": "text/html; charset=utf-8" }
    ]
  }'
```

--------------------------------

### Upload File to here.now

Source: https://here.now/docs

Uploads a file to the presigned URL obtained after creating a site. Ensure the Content-Type matches the file.

```bash
curl -X PUT "<upload.uploads[0].url>" \
  -H "Content-Type: text/html; charset=utf-8" \
  --data-binary @index.html
```

--------------------------------

### Finalize Site Publishing with here.now

Source: https://here.now/docs

Completes the site publishing process by sending the version ID. This is the final step after uploading files.

```bash
curl -sS -X POST "<finalizeUrl>" \
  -H "content-type: application/json" \
  -d '{ "versionId": "<versionId>" }'
```

--------------------------------

### Publish Site - Create Site

Source: https://here.now/docs

Initiates the process of publishing a site by providing file details. This step returns upload URLs and a finalize URL.

```APIDOC
## POST /api/v1/publish

### Description
Creates a new site entry and returns necessary URLs for uploading files and finalizing the publication.

### Method
POST

### Endpoint
/api/v1/publish

### Parameters
#### Request Body
- **files** (array) - Required - An array of file objects, each containing path, size, and contentType.
  - **path** (string) - Required - The path of the file.
  - **size** (integer) - Required - The size of the file in bytes.
  - **contentType** (string) - Required - The MIME type of the file.

### Request Example
```json
{
  "files": [
    { "path": "index.html", "size": 1234, "contentType": "text/html; charset=utf-8" }
  ]
}
```

### Response
#### Success Response (200)
- **siteUrl** (string) - The live URL of the published site.
- **uploads** (array) - An array of upload objects, each containing a presigned URL for uploading.
  - **url** (string) - The presigned URL for uploading a file.
- **finalizeUrl** (string) - The URL to finalize the site publication.
- **claimUrl** (string, optional) - A URL to claim the site for permanent storage (only for anonymous sites).
```

--------------------------------

### Create Subdomain Handle Request

Source: https://here.now/docs

Send a POST request to create a new subdomain handle. Requires a paid plan.

```json
{ "handle": "yourname" }
```

--------------------------------

### Create Site

Source: https://here.now/docs

Publishes a new site by uploading its files. This endpoint provides presigned URLs for file uploads and returns site details upon completion.

```APIDOC
## POST /api/v1/publish

### Description
Publishes a new site by uploading its files.

### Method
POST

### Endpoint
/api/v1/publish (alias: /api/v1/artifact)

### Request Body
- **files** (array) - Required - An array of file objects, each with `path`, `size`, `contentType`, and `hash`.
  - **path** (string) - Required - Relative path of the file (e.g., `index.html`).
  - **size** (integer) - Required - Size of the file in bytes.
  - **contentType** (string) - Required - MIME type of the file.
  - **hash** (string) - Optional - SHA-256 hash of the file.
- **ttlSeconds** (integer) - Optional - Expiry time in seconds. Ignored for anonymous sites.
- **displayName** (string) - Optional - Owner-facing Site title (max 80 chars).
- **displayDescription** (string) - Optional - Owner-facing Site summary (max 280 chars).
- **viewer** (object) - Optional - Metadata for auto-viewer pages.
  - **title** (string) - Title for the viewer.
  - **description** (string) - Description for the viewer.
  - **ogImagePath** (string) - Path to the Open Graph image.

### Request Example
```json
{
  "files": [
    { "path": "index.html", "size": 1234, "contentType": "text/html; charset=utf-8", "hash": "a1b2c3d4..." },
    { "path": "assets/app.js", "size": 999, "contentType": "text/javascript; charset=utf-8", "hash": "e5f6a7b8..." }
  ],
  "ttlSeconds": null,
  "displayName": "My site",
  "displayDescription": "A short summary shown in your dashboard and search results.",
  "viewer": {
    "title": "My site",
    "description": "Published by an agent",
    "ogImagePath": "assets/cover.png"
  }
}
```

### Response
#### Success Response (200)
- **slug** (string) - The unique slug for the published site.
- **siteUrl** (string) - The URL of the published site.
- **displayName** (string) - The display name of the site.
- **displayDescription** (string) - The display description of the site.
- **upload** (object) - Details about the file upload process.
  - **versionId** (string) - The version ID for the upload.
  - **uploads** (array) - Presigned URLs for uploading files.
  - **skipped** (array) - List of files skipped during upload.
  - **finalizeUrl** (string) - URL to finalize the upload.
  - **expiresInSeconds** (integer) - Time in seconds until upload links expire.

For anonymous sites, the response also includes:
- **claimToken** (string) - Token to claim the site.
- **claimUrl** (string) - URL to claim the site.
- **expiresAt** (string) - Expiration timestamp for the claim.
- **anonymous** (boolean) - Indicates if the site is anonymous.
- **warning** (string) - Important notice about saving claim information.

#### Response Example (Authenticated)
```json
{
  "slug": "bright-canvas-a7k2",
  "siteUrl": "https://bright-canvas-a7k2.here.now/",
  "displayName": "My site",
  "displayDescription": "A short summary shown in your dashboard and search results.",
  "upload": {
    "versionId": "01J...",
    "uploads": [
      {
        "path": "index.html",
        "method": "PUT",
        "url": "https://<presigned-url>",
        "headers": { "Content-Type": "text/html; charset=utf-8" }
      }
    ],
    "skipped": ["assets/app.js"],
    "finalizeUrl": "https://here.now/api/v1/publish/bright-canvas-a7k2/finalize",
    "expiresInSeconds": 3600
  }
}
```

#### Response Example (Anonymous)
```json
{
  "slug": "bright-canvas-a7k2",
  "siteUrl": "https://bright-canvas-a7k2.here.now/",
  "displayName": "My site",
  "displayDescription": "A short summary shown in your dashboard and search results.",
  "claimToken": "abc123...",
  "claimUrl": "https://here.now/claim?slug=bright-canvas-a7k2&token=abc123...",
  "expiresAt": "2026-02-19T01:00:00.000Z",
  "anonymous": true,
  "warning": "IMPORTANT: Save the claimToken and claimUrl. They are returned only once and cannot be recovered. Share the claimUrl with the user so they can keep the site permanently.",
  "upload": {
    "versionId": "01J...",
    "uploads": [
      {
        "path": "index.html",
        "method": "PUT",
        "url": "https://<presigned-url>",
        "headers": { "Content-Type": "text/html; charset=utf-8" }
      }
    ],
    "skipped": ["assets/app.js"],
    "finalizeUrl": "https://here.now/api/v1/publish/bright-canvas-a7k2/finalize",
    "expiresInSeconds": 3600
  }
}
```
```

--------------------------------

### Publish Drive Content Using Script

Source: https://here.now/docs

Use this script to publish a Drive version to a site. Specify the drive ID and optionally a version ID and client.

```bash
./scripts/publish.sh --from-drive drv_... --slug my-site
```

```bash
./scripts/publish.sh --from-drive drv_... --version dv_... --client cursor
```

--------------------------------

### Create Drive

Source: https://here.now/docs

Creates a new Drive. Requires Authorization header.

```APIDOC
## POST /api/v1/drives

### Description
Creates a new Drive.

### Method
POST

### Endpoint
/api/v1/drives

### Request Headers
- Authorization: Bearer <API_KEY> or Drive token
```

--------------------------------

### Manage Drives with Drive Helper Script

Source: https://here.now/docs

Use the `drive.sh` script to perform common Drive operations like creating, putting files, listing directories, and importing/exporting folders. It handles staged uploads and preserves ETags.

```bash
./scripts/drive.sh default

```

```bash
./scripts/drive.sh create "Research"

```

```bash
./scripts/drive.sh put Research notes/today.md --from ./notes/today.md

```

```bash
./scripts/drive.sh ls Research notes/

```

```bash
./scripts/drive.sh import My Drive agent-context/ --from ./notes --dry-run

```

```bash
./scripts/drive.sh export My Drive agent-context/ --to ./agent-context

```

```bash
./scripts/drive.sh share Research --perms write --prefix notes/ --ttl 7d

```

```bash
./scripts/drive.sh share Research --perms write --ttl 7d --manage-tokens --label "token manager"

```

--------------------------------

### Get Site Access Policy

Source: https://here.now/docs

Read the current access policy for a site, including the active mode, policy version, allowed emails, and allowed domains.

```json
{
  "access": {
    "mode": "restricted",
    "accessPolicyVersion": 3,
    "allowedEmails": ["person@example.com"],
    "allowedDomains": ["example.com"]
  }
}
```

--------------------------------

### Store API Key in Credentials File

Source: https://here.now/docs

This command creates the necessary directory and stores your API key in the `~/.herenow/credentials` file with restricted permissions. This is the recommended method for storing your API key.

```bash
mkdir -p ~/.herenow && echo "<API_KEY>" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials
```

--------------------------------

### Duplicate a Site with Optional Viewer Metadata

Source: https://here.now/docs

Use this endpoint to create a server-side copy of an existing site. The request body can optionally override viewer metadata like title and description. The new site is immediately live upon creation.

```json
{
  "viewer": {
    "title": "My Copy",
    "description": "Copy of bright-canvas-a7k2"
  }
}
```

--------------------------------

### Upload File with cURL

Source: https://here.now/docs

Use this command to upload a file to a presigned URL. Ensure the Content-Type and local-file path are correctly specified. Presigned URLs are valid for 1 hour.

```bash
curl -X PUT "<presigned-url>" \
  -H "Content-Type: <content-type>" \
  --data-binary @<local-file>
```

--------------------------------

### Get Account Analytics Data

Source: https://here.now/docs

Retrieves aggregated analytics data across all owned sites for paid accounts. Supported ranges include 24h, 7d, 30d, 90d, and all.

```bash
GET /api/v1/analytics?range=24h
```

```bash
GET /api/v1/analytics?range=30d
```

--------------------------------

### Duplicate a site

Source: https://here.now/docs

Creates a complete server-side copy of the site under a new slug. All files are copied server-side, and the new site is immediately live. Requires ownership of the source site.

```APIDOC
## POST /api/v1/publish/:slug/duplicate

### Description
Creates a complete server-side copy of the site under a new slug. All files are copied server-side — no client upload or finalize step needed. The new site is immediately live.

### Method
POST

### Endpoint
/api/v1/publish/:slug/duplicate

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the site to duplicate.

#### Request Body
- **viewer** (object) - Optional - Shallow-merged with the source site's viewer metadata. Only provided fields are overridden; omitted fields are preserved from the source.
  - **title** (string) - Optional - The title for the new site's viewer.
  - **description** (string) - Optional - The description for the new site's viewer.

### Request Example
```json
{
  "viewer": {
    "title": "My Copy",
    "description": "Copy of bright-canvas-a7k2"
  }
}
```

### Response
#### Success Response (200)
- **slug** (string) - The slug of the newly duplicated site.
- **siteUrl** (string) - The URL of the newly duplicated site.
- **sourceSlug** (string) - The slug of the original site that was duplicated.
- **status** (string) - The status of the duplicated site.
- **currentVersionId** (string) - The ID of the current version of the duplicated site.
- **filesCount** (integer) - The number of files copied.

#### Response Example
```json
{
  "slug": "warm-lake-f3k9",
  "siteUrl": "https://warm-lake-f3k9.here.now/",
  "sourceSlug": "bright-canvas-a7k2",
  "status": "active",
  "currentVersionId": "01J...",
  "filesCount": 36
}
```
```

--------------------------------

### Get Site Analytics Data

Source: https://here.now/docs

Retrieves analytics data for a specific site. Requires an API key and a paid plan. Supported ranges include 24h, 7d, 30d, 90d, and all.

```bash
GET /api/v1/publishes/:slug/analytics?range=24h
```

```bash
GET /api/v1/publishes/bright-canvas-a7k2/analytics?range=30d
```

--------------------------------

### API Error Response Example

Source: https://here.now/docs

This JSON object represents a typical error response from the public API. New agents should prefer structured fields like 'code', 'message', 'retry_after', and 'docs_url' for recovery.

```json
{
  "error": "Rate limit exceeded. Max 60 anonymous sites per hour.",
  "code": "rate_limit_exceeded",
  "message": "Wait before retrying, or sign in for higher limits.",
  "retry_after": 3600,
  "docs_url": "https://here.now/docs#limits"
}
```

--------------------------------

### Allow Access by Domain

Source: https://here.now/docs

Configure a site to allow access from any email address within a specified domain. If the site already has exact-email entries or other domains configured, read the current policy first.

```bash
curl -sS https://here.now/api/v1/publish/bright-canvas-a7k2/access \
  -X PATCH \
  -H "Authorization: Bearer $HERENOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "mode": "restricted", \
    "allowedEmails": [], \
    "allowedDomains": ["example.com"] \
  }'
```

--------------------------------

### Create or update a variable

Source: https://here.now/docs

Creates a new variable or updates an existing one. Variable names must be uppercase letters, digits, and underscores, starting with a letter. There's a limit of 50 variables per account and 4 KB per value. The `allowedUpstreams` field is optional and restricts which upstream domains the variable can be sent to.

```APIDOC
## PUT /api/v1/me/variables/:name

### Description
Creates or updates a variable.

### Method
PUT

### Endpoint
`/api/v1/me/variables/:name`

### Headers
`Authorization: Bearer <API_KEY>`

### Request Body
- **value** (string) - Required - The value of the variable.
- **allowedUpstreams** (array) - Optional - A list of upstream domains the variable can be sent to.

### Request Example
```json
{
  "value": "sk-or-v1-abc123",
  "allowedUpstreams": ["openrouter.ai"]
}
```

### Response
(No specific success response details provided in the source)
```

--------------------------------

### Create Site Request Body

Source: https://here.now/docs

This JSON object defines the files and metadata for publishing a new site. Ensure file paths are relative and hashes are provided for efficient updates.

```json
{
  "files": [
    { "path": "index.html", "size": 1234, "contentType": "text/html; charset=utf-8", "hash": "a1b2c3d4..." },
    { "path": "assets/app.js", "size": 999, "contentType": "text/javascript; charset=utf-8", "hash": "e5f6a7b8..." }
  ],
  "ttlSeconds": null,
  "displayName": "My site",
  "displayDescription": "A short summary shown in your dashboard and search results.",
  "viewer": {
    "title": "My site",
    "description": "Published by an agent",
    "ogImagePath": "assets/cover.png"
  }
}
```

--------------------------------

### Add a Custom Domain

Source: https://here.now/docs

Use this cURL command to add a custom domain to your Here Now site. Ensure you replace `<API_KEY>` with your actual API key. The response will contain DNS instructions for verification.

```bash
curl -sS https://here.now/api/v1/domains \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
```

--------------------------------

### Link to Subdomain Handle

Source: https://here.now/docs

Create a link to a specific location on your subdomain handle. Omit the 'domain' parameter.

```json
{ "location": "docs", "slug": "bright-canvas-a7k2" }
```

--------------------------------

### Create an API Key

Source: https://here.now/docs

Use this cURL command to create a new named API key. The name helps in identifying the key's purpose.

```bash
curl -sS https://here.now/api/v1/me/keys \
  -H "Authorization: Bearer <API_API_KEY>" \
  -H "content-type: application/json" \
  -d '{"name": "claude"}'
```

--------------------------------

### Publish from Drive

Source: https://here.now/docs

Publishes a Drive version server-side to create a published site. Requires Authorization header.

```APIDOC
## POST /api/v1/publish/from-drive

### Description
Publishes a Drive version server-side to create a normal published site.

### Method
POST

### Endpoint
/api/v1/publish/from-drive

### Request Body
{
  "driveId": "drv_...",
  "versionId": "dv_...",
  "slug": "optional"
}

### Request Headers
- Authorization: Bearer <API_KEY> or Drive token
```

--------------------------------

### Response for Site Duplication

Source: https://here.now/docs

This is a sample response received after successfully duplicating a site. It includes the new site's slug, URL, source slug, status, current version ID, and file count.

```json
{
  "slug": "warm-lake-f3k9",
  "siteUrl": "https://warm-lake-f3k9.here.now/",
  "sourceSlug": "bright-canvas-a7k2",
  "status": "active",
  "currentVersionId": "01J...",
  "filesCount": 36
}
```

--------------------------------

### Finalize Site Deployment

Source: https://here.now/docs

Send a POST request to finalize a site deployment. For owned sites, include an Authorization header. Anonymous sites can finalize without authentication.

```json
{ "versionId": "01J..." }
```

--------------------------------

### Add a Domain

Source: https://here.now/docs

Adds a custom domain to your Here Now account. The response includes DNS instructions for verification.

```APIDOC
## POST /api/v1/domains

### Description
Adds a custom domain to your Here Now account. The response includes DNS instructions for verification.

### Method
POST

### Endpoint
/api/v1/domains

### Request Body
- **domain** (string) - Required - The custom domain name to add.

### Request Example
```json
{
  "domain": "example.com"
}
```

### Response
#### Success Response (200)
- **dns_instructions** (array) - Instructions for setting up DNS records.
  - **type** (string) - The type of DNS record (e.g., A, CNAME).
  - **host** (string) - The host for the DNS record.
  - **value** (string) - The value for the DNS record.
- **status** (string) - The current status of the domain (e.g., pending, active).
```

--------------------------------

### Publish Drive Content Using API

Source: https://here.now/docs

This API route allows account owners to publish a Drive version server-side. It snapshots the selected Drive version into a published site.

```json
{ "driveId": "drv_...", "versionId": "dv_...", "slug": "optional" }
```

--------------------------------

### List Drives

Source: https://here.now/docs

Lists all Drives associated with the account. Requires Authorization header.

```APIDOC
## GET /api/v1/drives

### Description
Lists all Drives associated with the account.

### Method
GET

### Endpoint
/api/v1/drives

### Request Headers
- Authorization: Bearer <API_KEY> or Drive token
```

--------------------------------

### Subdomain Handles API

Source: https://here.now/docs

Manage your here.now subdomain handles. Claiming a subdomain handle requires a paid plan.

```APIDOC
## POST /api/v1/handle

### Description
Creates a new subdomain handle.

### Method
POST

### Endpoint
/api/v1/handle

### Request Body
- **handle** (string) - Required - The desired subdomain handle (e.g., "yourname").

### Request Example
```json
{
  "handle": "yourname"
}
```

### Response
#### Success Response (200)
- **handle** (string) - The created subdomain handle.
- **hostname** (string) - The full hostname (e.g., "yourname.here.now").

#### Response Example
```json
{
  "handle": "yourname",
  "hostname": "yourname.here.now"
}
```
```

```APIDOC
## GET /api/v1/handle

### Description
Retrieves information about the authenticated user's subdomain handle.

### Method
GET

### Endpoint
/api/v1/handle
```

```APIDOC
## PATCH /api/v1/handle

### Description
Updates an existing subdomain handle. Changing a subdomain handle keeps the same underlying namespace, so existing links move with the new name automatically.

### Method
PATCH

### Endpoint
/api/v1/handle

### Request Body
- **handle** (string) - Required - The new desired subdomain handle.

### Note
Subdomain handle format: lowercase letters/numbers/hyphens, 2-30 chars, no leading/trailing hyphens.
```

```APIDOC
## DELETE /api/v1/handle

### Description
Deletes a subdomain handle. This removes the namespace and deletes its links.

### Method
DELETE

### Endpoint
/api/v1/handle
```

--------------------------------

### Finalize Deployment Response

Source: https://here.now/docs

This is a successful response after finalizing a site deployment, indicating the new version and site URL.

```json
{
  "success": true,
  "slug": "bright-canvas-a7k2",
  "siteUrl": "https://bright-canvas-a7k2.here.now/",
  "previousVersionId": null,
  "currentVersionId": "01J..."
}
```

--------------------------------

### Upload Files

Source: https://here.now/docs

Upload files to presigned URLs. Multiple uploads can occur in parallel. Presigned URLs are valid for 1 hour.

```APIDOC
## Upload files
For each entry in `upload.uploads[]`, PUT the file to the presigned URL:
```
curl -X PUT "<presigned-url>" \
  -H "Content-Type: <content-type>" \
  --data-binary @<local-file>
```
```

--------------------------------

### Proxy Route Configuration

Source: https://here.now/docs

Configure proxy routes in `.herenow/proxy.json` to map site paths to external APIs. Variable references like `${VAR_NAME}` in headers are resolved server-side.

```json
// .herenow/proxy.json
{
  "proxies": {
    "/api/chat": {
      "upstream": "https://openrouter.ai/api/v1/chat/completions",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer ${OPENROUTER_API_KEY}"
      }
    },
    "/api/db/*": {
      "upstream": "https://xyz.supabase.co/rest/v1",
      "headers": {
        "apikey": "${SUPABASE_KEY}"
      }
    }
  }
}
```

--------------------------------

### List Drive Tokens

Source: https://here.now/docs

Lists active tokens for a Drive. Requires Authorization header.

```APIDOC
## GET /api/v1/drives/:driveId/tokens

### Description
Lists active tokens for a Drive.

### Method
GET

### Endpoint
/api/v1/drives/:driveId/tokens

### Request Headers
- Authorization: Bearer <API_KEY> or Drive token
```

--------------------------------

### Create API Key

Source: https://here.now/docs

Creates a new named API key for your account. Each key can be individually revoked and is useful for differentiating agents or tools.

```APIDOC
## POST /api/v1/me/keys

### Description
Creates a new named API key.

### Method
POST

### Endpoint
/api/v1/me/keys

### Request Body
- **name** (string) - Required - The name for the API key.

### Request Example
```json
{
  "name": "claude"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the key.
- **name** (string) - The name of the key.
- **key** (string) - The full API key.
- **keySuffix** (string) - The last few characters of the API key.
- **createdAt** (string) - The timestamp when the key was created.

#### Response Example
```json
{
  "id": "9f4e...",
  "name": "claude",
  "key": "hnk_<64 hex chars>",
  "keySuffix": "a1b2",
  "createdAt": "2026-06-11T00:00:00.000Z"
}
```
```

--------------------------------

### Return Site to Public Link Access

Source: https://here.now/docs

Resets the site's access mode to 'anyone_with_link', making it publicly accessible via a link without requiring specific email or domain permissions.

```bash
curl -sS https://here.now/api/v1/publish/bright-canvas-a7k2/access \
  -X PATCH \
  -H "Authorization: Bearer $HERENOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "anyone_with_link" }'
```

--------------------------------

### Link to Custom Domain

Source: https://here.now/docs

Create a link to a specific location on a custom domain. Include the 'domain' parameter.

```json
{ "location": "", "slug": "bright-canvas-a7k2", "domain": "example.com" }
```

--------------------------------

### Create Record in Browser

Source: https://here.now/docs

Creates a new record in a collection. Use an Idempotency-Key header for safe retries.

```javascript
// Create a record. Use Idempotency-Key when a retry might repeat the same submit.
const createRes = await fetch("./.herenow/data/entries", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify({
    name: "Ada",
    message: "See you there",
    attending: true
  })
});
const { record } = await createRes.json();
```

--------------------------------

### Stage File Upload

Source: https://here.now/docs

Stages a file for upload, returning a presigned PUT URL. Requires Authorization header.

```APIDOC
## POST /api/v1/drives/:driveId/files/uploads

### Description
Stages a file for upload and returns a presigned PUT URL.

### Method
POST

### Endpoint
/api/v1/drives/:driveId/files/uploads

### Request Headers
- Authorization: Bearer <API_KEY> or Drive token
```

--------------------------------

### Mint Drive Token

Source: https://here.now/docs

Mints a scoped token for a Drive. Can optionally include `manageTokens` permission. Requires Authorization header.

```APIDOC
## POST /api/v1/drives/:driveId/tokens

### Description
Mints a scoped token for a Drive.

### Method
POST

### Endpoint
/api/v1/drives/:driveId/tokens

### Request Body
{
  "perms": {
    "read": true,
    "write": false,
    "manageTokens": true
  },
  "ttl": "1h"
}

### Request Headers
- Authorization: Bearer <API_KEY> or Drive token

### Response
#### Success Response (200)
- secret (string) - The one-time live token secret.
- token (object) - Token metadata.
  - id (string)
  - driveId (string)
  - expiresAt (string)
  - perms (object)

```

--------------------------------

### List sites

Source: https://here.now/docs

Retrieves a list of all sites owned by the authenticated user. Supports an alias for artifacts.

```APIDOC
## List sites

### Description
Returns all sites owned by the authenticated user.

### Method
GET

### Endpoint
GET /api/v1/publishes (alias: GET /api/v1/artifacts)

### Parameters
#### Query Parameters
- **Authorization** (string) - Required - Bearer <API_KEY>

### Response
#### Success Response (200)
- **publishes** (array) - Description of the list of published sites.
  - **slug** (string) - The unique identifier for the site.
  - **siteUrl** (string) - The live URL of the site.
  - **updatedAt** (string) - The timestamp when the site was last updated.
  - **expiresAt** (null) - The expiration timestamp for the site (if applicable).
  - **status** (string) - The current status of the site (e.g., 'active').
  - **currentVersionId** (string) - The ID of the current live version.
  - **pendingVersionId** (null) - The ID of any pending version (if applicable).

### Response Example
```json
{
  "publishes": [
    {
      "slug": "bright-canvas-a7k2",
      "siteUrl": "https://bright-canvas-a7k2.here.now/",
      "updatedAt": "2026-02-18T...",
      "expiresAt": null,
      "status": "active",
      "currentVersionId": "01J...",
      "pendingVersionId": null
    }
  ]
}
```
```

--------------------------------

### Create a record

Source: https://here.now/docs

Use this cURL command to create a new record in a collection. It requires an API key, content type, and a JSON payload. An Idempotency-Key is recommended for safe retries.

```bash
# Create a record.
curl -sS "https://here.now/api/v1/publishes/{slug}/data/entries" \
  -X POST \
  -H "Authorization: Bearer $HERENOW_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Ada","message":"See you there","attending":true}'
```