Skip to main content

Discovery API

F1: Agentless Discovery endpoints for scanning AWS environments to find unregistered AI agents and MCP servers.

All endpoints require authentication via JWT or API key and enforce tenant isolation via organization_id.

Endpoints​

POST /api/v1/discovery/sources​

Create a discovery scan source (AWS account with IAM role).

Request Body:

{
  "display_name": "Production AWS Account",
  "role_arn": "arn:aws:iam::123456789012:role/AscendDiscoveryRole",
  "regions": ["us-east-1", "us-east-2"],
  "scan_scope": ["cloudwatch", "lambda", "ecs", "apigateway"]
}

Response: 201 Created

{
  "source_id": "src-abc123",
  "external_id": "ascend-ext-abc123",
  "status": "active",
  "display_name": "Production AWS Account"
}

GET /api/v1/discovery/sources​

List all configured scan sources for the organization.

Response: 200 OK

{
  "sources": [
    {
      "source_id": "src-abc123",
      "display_name": "Production AWS Account",
      "status": "active",
      "last_scan_at": "2026-04-09T14:30:00Z"
    }
  ]
}

POST /api/v1/discovery/scan/start​

Start a discovery scan against a configured source.

Request Body:

{
  "source_id": "src-abc123",
  "scan_types": ["cloudwatch", "lambda", "ecs"]
}

Response: 200 OK

{
  "scan_run_id": "scan-xyz789",
  "status": "running",
  "started_at": "2026-04-10T10:00:00Z"
}

GET /api/v1/discovery/scan/:scan_run_id​

Poll scan status and results.

Response: 200 OK

{
  "scan_run_id": "scan-xyz789",
  "status": "completed",
  "discovered_count": 5,
  "started_at": "2026-04-10T10:00:00Z",
  "completed_at": "2026-04-10T10:02:30Z"
}

GET /api/v1/discovery/agents​

List all discovered agents for the organization.

Response: 200 OK

{
  "agents": [
    {
      "discovery_id": "disc-001",
      "agent_name": "Lambda GPT Handler",
      "agent_framework": "langchain",
      "status": "unregistered",
      "risk_indicator": "high",
      "confidence": 0.92,
      "source_type": "aws_lambda"
    }
  ]
}

POST /api/v1/discovery/agents/:discovery_id/register​

Register a discovered agent into the Agent Registry.

Request Body:

{
  "display_name": "GPT Handler Agent",
  "agent_type": "supervised"
}

Response: 200 OK

{
  "agent_id": "gpt-handler-001",
  "status": "active",
  "registered_from": "disc-001"
}

POST /api/v1/discovery/agents/:discovery_id/dismiss​

Dismiss a discovered agent (mark as reviewed, not a risk).

Response: 200 OK

GET /api/v1/discovery/mcp/results​

List MCP server scan results.

Response: 200 OK

{
  "results": [
    {
      "server_name": "internal-mcp-server",
      "endpoint": "https://mcp.internal.com",
      "tools_detected": 12,
      "trust_level": "unverified"
    }
  ]
}

DELETE /api/v1/discovery/sources/:source_id​

Remove a scan source.

Response: 204 No Content