Developers

CLI and API

Scrape pages and audit websites from your terminal or your own code. The CLI signs in to your novagentum account and uses the same balance, workspace spending permissions, limits and prices as the dashboard. API keys for servers and CI are coming later.

Install the CLI

macOS and Linux (x64 and arm64):

curl -fsSL https://www.novagentum.ai/install.sh | sh

The script downloads the release for your system from GitHub, checks its SHA-256 checksum and verifies the minisign signature (install minisign first for signature checks). Set NOVAGENTUM_VERSION=0.1.0 to pin a version and NOVAGENTUM_INSTALL_DIR to change the install folder (default ~/.local/bin). Windows: download novagentum-windows-x64.exe from the GitHub release.

Use the CLI

novagentum login
novagentum scrape https://example.com > page.md
novagentum crawl https://example.com --limit 25
novagentum loginSign in through your browser
novagentum whoamiAccount, workspaces and balance
novagentum usage [-w workspace]Balance for your account or a workspace
novagentum scrape <url> [--format markdown|html|json] [-o file]Scrape one page
novagentum crawl <url> [--limit 25]Crawl and audit a website
novagentum crawl status <id>Status and result of a crawl
novagentum runs listRecent crawls and scrapes
novagentum logoutSign out and revoke the CLI session

Add --json for machine-readable output and -w <slug> to spend a workspace balance. Exit codes: 0 success, 1 error, 2 usage, 3 not signed in, 4 insufficient credits. Credentials are stored in ~/.config/novagentum/credentials.json (readable only by you). For CI, set NOVAGENTUM_TOKEN to an access token.

Authentication

novagentum login uses the OAuth device flow: it shows a code, you approve it at https://www.novagentum.ai/cli/activate while signed in, and the CLI receives its own session. Send the access token as Authorization: Bearer <token>. Only approve codes you started yourself.

API endpoints

Base URL https://www.novagentum.ai. Successful responses are { "success": true, "data": … }; errors are { "success": false, "error": "…", "code": "…" } with codes such as INSUFFICIENT_BALANCE (402), WORKSPACE_SPEND_NOT_ALLOWED (403) and QUOTE_CHANGED (409). Reuse a requestId to retry without paying twice. The full schema is in openapi.json.

  • POST/api/v1/scrape

    Scrape one page. Returns markdown, HTML, links and metadata. Failed fetches are not charged.

    { "url": "https://example.com", "workspaceId"?: uuid, "requestId"?: uuid }

  • GET/api/v1/scrape/{id}

    Reopen a saved scrape for 30 days.

  • POST/api/v1/crawl

    Crawl and audit a website. Reserves the quoted maximum and charges only for audited pages.

    { "url": "https://example.com", "limit": 10, "workspaceId"?: uuid, "requestId"?: uuid, "quotedMaximumCents"?: int, "quotedPriceVersion"?: string }

  • GET/api/v1/crawl

    List your crawls and scrapes, newest first.

  • GET/api/v1/crawl/{id}

    Status (queued, running, completed or failed) and the full audit result.

  • DELETE/api/v1/crawl/{id}

    Delete a finished crawl or scrape and its stored content.

  • GET/api/v1/usage

    Credits or pay-as-you-go balance for your account or a workspace.

  • GET/api/crawl/quote?maxPages=10(public)

    Public price quote for a crawl.

curl -s https://www.novagentum.ai/api/v1/scrape \
  -H "Authorization: Bearer $NOVAGENTUM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'