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
GET /agent/compute/vms/{id} VM details + live metrics
GET /agent/compute/os-templates Available operating systems
GET /agent/compute/regions Available regions
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.