API Documentation

Overview

Sites — publish websites and files at https://a7een.doy.tech/s/<slug>.
Drives — private cloud storage for your agents.
Authenticate with Authorization: Bearer <API_KEY> (issued on sign-in) or a logged-in browser session. Drive read routes also accept a scoped Drive token via ?token=.

Install here

Install the here skill so your agent can publish automatically:

# Global install (recommended)
npx skills add heredotnow/skill --skill here-now -g

# Project-local install (no -g flag)
npx skills add heredotnow/skill --skill here-now

# Fallback installer
curl -fsSL https://a7een.doy.tech/install.sh | bash

Once installed, agents can publish with a single script call. Store your API key:

mkdir -p ~/.herenow && echo "API_KEY" > ~/.herenow/credentials

Key resolution order (first match wins): --api-key flag → $HERENOW_API_KEY env → ~/.herenow/credentials file.

Quick start

Publish a site in three steps. You need an API key — sign in by email and copy the a7een_… key from the instructions page.

1. Create site (get presigned URLs)

curl -sS https://a7een.doy.tech/api/v1/publish \
  -H "Authorization: Bearer a7een_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-site",
    "title": "My Site",
    "files": [
      { "path": "index.html", "size": 1234, "hash": "<sha256-of-file>" }
    ]
  }'

The response contains siteUrl, presigned upload.uploads[], and a upload.finalizeUrl.

2. Upload changed files

curl -X PUT "<upload.uploads[0].url>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @index.html

3. Finalize (go live)

curl -sS -X POST "<upload.finalizeUrl>" \
  -H "Authorization: Bearer a7een_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "files": [
    { "path": "index.html", "size": 1234, "hash": "<sha256-of-file>" }
  ] }'

Authentication

Two ways to authenticate:

• ● Bearer API key — include Authorization: Bearer <API_KEY>. Keys are issued on sign-in (a7een_…) and verified by SHA-256 hash, so the plain key is shown only once.
• ● Browser session — after signing in via the web app, API requests from the same browser session are authenticated automatically.
• ● Drive read tokens — read-only file and list endpoints accept a scoped Drive token via ?token=drv_… instead of the header.

Authorization: Bearer a7een_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Requests without a valid key or session return 401 with code unauthenticated or invalid_api_token.

Getting an API key

Sign-in is email-based: submit your email to receive a magic link. Opening the link creates your account (if new), issues an API key, and shows the agent instructions page.

1. Request a magic link

curl -sS -X POST https://a7een.doy.tech/start \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

2. Open the emailed link

The link signs you in, creates your personal team, and issues a fresh a7een_… API key. The key is shown on the /agent/instructions page at that moment — store it somewhere safe, the plain key is not shown again.

Sites

Publish HTML, documents, images, PDFs, videos, and static files to live URLs. The publishing workflow is three steps: create (get presigned URLs) → upload files to S3 → finalize (activate version).

⚡ SPA routing

For single-page apps (React, Vue, Svelte): enable SPA mode so unknown paths serve index.html instead of 404. Static assets still resolve normally — only paths not matching any file fall through to the index.html fallback.

curl -sS -X PATCH https://a7een.doy.tech/api/v1/publish/my-site/metadata \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "is_spa": true }'

Use root-relative asset paths (/assets/app.js). Vite and Create React App do this by default.

🏢 Features not available on self-hosted instances

The following features exist in the managed here.now SaaS and are referenced by the external documentation. They are not implemented on self-hosted instances like this one — the endpoints below do not exist here and return 404.

Drives

Private cloud folders for agents to store files and share them across sessions. Uploads are single-step: POST /files/uploads returns a presigned S3 PUT URL, and you upload directly to it. Reads return file contents inline. Every account gets a default Drive named Default (5 GB).

📤 Sharing & tokens

Use your account API key for full-Drive access. Use scoped Drive tokens when you need narrower access (read-only, path-restricted, time-limited, per-agent). Share the plain_text_token with another agent plus the Drive ID and this API base; the recipient calls read routes with ?token=<token> and must stay inside path_restriction when present.

# Mint a read-only token scoped to notes/ for another agent
curl -sS -X POST https://a7een.doy.tech/api/v1/drives/1/tokens \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "docs-writer", "permissions": "read", "path_restriction": "notes/" }'

# Recipient reads a file with the token (no Authorization header needed)
curl https://a7een.doy.tech/api/v1/drives/1/files/notes/report.txt?token=<plain_text_token>

Error responses

All errors return JSON with a stable error field plus structured fields for agent recovery.

{
  "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://a7een.doy.tech/docs#limits"
}

Limits & plans

Total storage is shared by published site versions and current Drive files. Drive version history is retained by time window and does not count toward the storage quota.

Agent discovery

here publishes well-known discovery files so agents can find the product, docs, API spec, and skill surfaces without scraping the homepage.

OpenAPI spec

The stable public API is described by an OpenAPI 3.1 specification. Agents can use it to discover request schemas, response schemas, authentication, and operation IDs. Import into Postman, Insomnia, or your agent's tool registry.