Skip to content
Agent tooling · Discovery endpoint

Agent tooling

Discovery endpoint

The first call every agent makes. Returns everything needed: account info, limits, available products with regions and OS templates, existing projects, and a full self-describing API schema.

On this page7 sections

Endpoint#

HTTP
GET https://edge.network/agent
Authorization: Bearer ea_live_...

This single call gives the agent everything it needs to understand the account, what it can do and what already exists. Without an Authorization header the same URL returns a public onboarding document instead: what Edge is, how to get a code (including autonomous self-signup), and the starter system prompt at GET /agent/prompt.

What’s returned#

Field Description
account Account ID, name, plan and the name of the agent access code
budget Monthly spending cap, cap type (soft/hard) and currency
products Available products with usage limits. Compute includes regions, OS templates and VM sizes inline.
capabilities Actions the agent is permitted to perform (based on access code permissions)
projects Existing projects with description, resources and creation date
endpoints Full self-describing API schema: every available endpoint with parameters, types, defaults and descriptions. This is the core of the discovery system.
notes Guidance on dry run, idempotency, error handling and the tell_user convention
docs_url Link to full documentation. JSON version available via Accept: application/json header.
tell_user Human-readable summary the agent can relay to the user

Self-describing API#

The endpoints object is the most important part of the discovery response. It describes every available endpoint with its parameters, types, required fields, defaults and descriptions. An agent can read this once and know how to call every API without crawling documentation.

For mutating endpoints (POST, PATCH, DELETE), the schema includes the full request body shape. For example, the POST /agent/deploy/app endpoint describes every compute parameter (os, size, region), networking options (firewall rules) and optional CDN/DNS configuration.

Example response#

Abbreviated for readability. The actual endpoints object contains full parameter schemas.

JSON
{
  "api_version": "1",
  "docs_url": "https://edge.network/docs",
  "account": {
    "id": "acc_abc123",
    "name": "My Company",
    "plan": "scaleup",
    "agent_name": "Cursor - Production"
  },
  "budget": {
    "cap_monthly": 5000,
    "cap_type": "soft",
    "currency": "USD"
  },
  "products": {
    "compute": {
      "enabled": true,
      "limits": {
        "vms": { "max": 10, "used": 2 },
        "vcpu": { "max": 16, "used": 4 },
        "ram_gb": { "max": 32, "used": 8 }
      },
      "regions": [
        { "id": "london", "name": "London", "location": "London, UK" },
        { "id": "new-york", "name": "New York", "location": "New York, US" }
      ],
      "os_templates": [
        { "id": "ubuntu-24.04", "name": "Ubuntu 24.04 LTS", "family": "ubuntu" },
        { "id": "debian-12", "name": "Debian 12", "family": "debian" }
      ],
      "sizes": ["nano", "small", "medium", "large", "xlarge"],
      "endpoint": "/agent/compute"
    },
    "cdn": { "enabled": true, "endpoint": "/agent/cdn" },
    "storage": {
      "enabled": true,
      "usage": { "buckets": 3, "total_size_bytes": 524288000 },
      "endpoint": "/agent/storage"
    },
    "dns": { "enabled": true, "endpoint": "/agent/dns" },
    "shield": {
      "enabled": true,
      "description": "Free, privacy-first CAPTCHA alternative...",
      "modes": ["managed", "non-interactive", "invisible"],
      "agent_policies": ["allow", "challenge", "block"],
      "pricing": "Free: unlimited widgets and verifications.",
      "endpoint": "/agent/shield"
    },
    "assist": {
      "enabled": true,
      "description": "AI answers for any website, grounded in its own content...",
      "pricing": "250 answered questions per site per month free, then $0.01/question...",
      "index_format": "JSON at a public URL: { \"pages\": [{ \"url\", \"title\", \"text\" }] }...",
      "endpoint": "/agent/assist"
    }
  },
  "capabilities": [
    "deploy_static_site", "deploy_app", "upload_assets",
    "provision_vm", "manage_dns", "check_health", "scale",
    "protect_forms", "add_ai_answers", "teardown"
  ],
  "projects": [
    {
      "id": "proj_xyz",
      "name": "my-portfolio",
      "description": "Portfolio site",
      "resources": [
        { "type": "storage", "id": "my-portfolio", "name": "my-portfolio" },
        { "type": "cdn", "id": "dep_abc", "name": "my-portfolio" }
      ],
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "endpoints": {
    "POST /agent/deploy/static-site": {
      "description": "Deploy a static website from uploaded files or a git repo."
    },
    "POST /agent/deploy/app": {
      "description": "Deploy a VM-based app with optional CDN and DNS."
    },
    "PATCH /agent/deploy/{projectId}": {
      "description": "Update an existing deployment."
    },
    "GET /agent/projects": { "description": "List all projects" },
    "POST /agent/projects": { "description": "Create a project" },
    "DELETE /agent/projects/{id}": {
      "description": "Teardown project and all resources."
    },
    "GET /agent/compute/vms": { "description": "List VMs" },
    "GET /agent/compute/os-templates": { "description": "List available OS" },
    "GET /agent/compute/regions": { "description": "List regions" },
    "GET /agent/compute/scripts": { "description": "List startup scripts" },
    "GET /agent/compute/firewall": { "description": "List security groups" },
    "POST /agent/compute/firewall": { "description": "Create security group" },
    "GET /agent/cdn/deployments": { "description": "List CDN deployments" },
    "GET /agent/storage/buckets": { "description": "List storage buckets" },
    "POST /agent/storage/buckets": { "description": "Create bucket" },
    "GET /agent/dns/zones": { "description": "List DNS zones" },
    "POST /agent/dns/zones/{id}/records": { "description": "Add DNS record" },
    "GET /agent/shield/widgets": { "description": "List Shield widgets" },
    "POST /agent/shield/widgets": { "description": "Create a bot-protection widget" },
    "GET /agent/assist/sites": { "description": "List Edge Assist sites" },
    "POST /agent/assist/sites": { "description": "Create an AI-answers site" }
  },
  "notes": {
    "dry_run": "Add X-Dry-Run: true header to preview without making changes.",
    "idempotency": "Add Idempotency-Key header for safe retries.",
    "tell_user": "Every response includes a tell_user field with a plain English summary.",
    "errors": "Error responses include code, message, suggestions, and tell_user."
  },
  "tell_user": "Connected to Edge Network as \"My Company\". 6 products available: compute, cdn, storage, dns, shield, assist. 1 active project."
}

All endpoints#

Every endpoint available to agents. All responses include tell_user. All mutating endpoints support X-Dry-Run: true.

Text
# Composite Actions
POST   /agent/deploy/static-site        Deploy static site (upload or git)
POST   /agent/deploy/app                Deploy VM-based application
PATCH  /agent/deploy/{projectId}         Update existing deployment

# Projects
GET    /agent/projects                   List projects
POST   /agent/projects                   Create project
GET    /agent/projects/{id}              Project details
GET    /agent/projects/{id}/health       Health check all resources
POST   /agent/projects/{id}/scale        Scale compute resources
DELETE /agent/projects/{id}              Teardown project + all resources

# Compute
GET    /agent/compute/vms                List VMs
POST   /agent/compute/vms                Create VM directly
GET    /agent/compute/vms/{id}           VM details + live metrics + ssh.command
GET    /agent/compute/os-templates       Available operating systems
GET    /agent/compute/regions            Available regions
GET    /agent/compute/scripts            Startup scripts (library + custom)

# SSH Keys
GET    /agent/compute/ssh-keys                       List saved SSH keys
POST   /agent/compute/ssh-keys                       Save an SSH public key
DELETE /agent/compute/ssh-keys/{id}                  Delete an SSH key
GET    /agent/compute/vms/{id}/ssh-keys              List keys attached to VM
POST   /agent/compute/vms/{id}/ssh-keys/{keyId}      Attach key to existing VM
DELETE /agent/compute/vms/{id}/ssh-keys/{keyId}      Detach key from VM

# Firewall
GET    /agent/compute/firewall                       List security groups
GET    /agent/compute/firewall/{id}                  Security group details
POST   /agent/compute/firewall                       Create security group
POST   /agent/compute/vms/{id}/firewall/{groupId}    Attach firewall
DELETE /agent/compute/vms/{id}/firewall/{groupId}    Detach firewall

# CDN
GET    /agent/cdn/deployments            List CDN deployments

# Storage
GET    /agent/storage/buckets            List buckets
POST   /agent/storage/buckets            Create bucket

# DNS
GET    /agent/dns/zones                  List zones
GET    /agent/dns/zones/{id}             Zone details + records
POST   /agent/dns/zones/{id}/records     Add DNS record

# Shield (bot protection, free)
GET    /agent/shield/widgets             List widgets
POST   /agent/shield/widgets             Create widget (returns secret + embed snippet)
PATCH  /agent/shield/widgets/{id}        Update widget
DELETE /agent/shield/widgets/{id}        Revoke widget
GET    /agent/shield/widgets/{id}/stats  Traffic stats

# Assist (AI answers)
GET    /agent/assist/sites               List sites
POST   /agent/assist/sites               Create site (returns sitekey + embed snippet)
PATCH  /agent/assist/sites/{id}          Update site
DELETE /agent/assist/sites/{id}          Delete site
POST   /agent/assist/sites/{id}/reingest Index the site's content now
GET    /agent/assist/sites/{id}/overview Usage + health
GET    /agent/assist/sites/{id}/questions Question log

Key concepts#

  • Dry run: Add X-Dry-Run: true to any mutating request to preview what would happen without making changes. The response shows what would be created, modified or deleted.
  • Idempotency: Add Idempotency-Key: unique-id to POST requests. If the same key is sent again, the original response is returned without re-executing the action. Safe for retries.
  • tell_user: Every response includes a tell_user field: a plain English summary the agent can relay directly to the user without interpretation. Error responses include it too.
  • Error handling: Errors return a structured object with code, message and tell_user. The agent can use the code for programmatic handling and tell_user for reporting.
  • SSH keys and VMs: The default SSH user is root. Pass keys at creation via compute.ssh_key or compute.ssh_key_ids. If you forget, do not recreate the VM. Save the key with POST /agent/compute/ssh-keys, then attach with POST /agent/compute/vms/{vmId}/ssh-keys/{keyId}. Edge pushes it to the running VM via the guest agent in ~10s. See Deploy an application → SSH access for the full flow.

See also#

Something unclear or out of date? Tell us

View as Markdown Get support