--- title: "Discovery Endpoint" description: "The agent's entry point to Edge Network. Returns capabilities, limits, existing resources, and a full self-describing API schema." url: https://edge.network/docs/agent/discovery/ --- # 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. ## Endpoint ``` 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. ## 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 — no documentation crawling needed. 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. The `endpoints` schema in the actual response is much more detailed than the abbreviated example below — it includes full parameter definitions with types, enums, defaults, and descriptions for every field. ## Example Response Abbreviated for readability. The actual `endpoints` object contains full parameter schemas. ``` { "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" } }, "capabilities": [ "deploy_static_site", "deploy_app", "upload_assets", "provision_vm", "manage_dns", "check_health", "scale", "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/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" } }, "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\". 4 products available: compute, cdn, storage, dns. 1 active project." } ``` ## All Endpoints Every endpoint available to agents. All responses include `tell_user`. All mutating endpoints support `X-Dry-Run: true`. ``` # 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 # 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 ``` ## 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 & VMs 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 Application → SSH Access](https://edge.network/docs/agent/deploy-app#ssh-access) for the full flow. ## See Also [Access Codes Create and manage agent credentials](https://edge.network/docs/agent/access-codes) [Deploy Static Site Upload files or deploy from git](https://edge.network/docs/agent/deploy-static-site) [Back to Docs](https://edge.network/docs) [Need help?](https://edge.network/support)