Overview

The scanner uploads a JSON payload to POST /api/v1/scans/upload. This page documents the payload format for developers building custom scanners or integrations.

Payload structure

{
  "version": "1",
  "repo_name": "acme-api",
  "repo_url": "https://github.com/acme/acme-api",
  "branch": "main",
  "commit_sha": "a1b2c3d4e5f6",
  "findings": [
    {
      "service_name": "api-gateway",
      "service_type": "service",
      "language": "Python",
      "version": "2.1.0",
      "endpoints": [
        {
          "method": "GET",
          "path": "/api/v1/health",
          "kind": "rest"
        }
      ],
      "connections": [
        {
          "target_service": "user-service",
          "protocol": "rest",
          "target_endpoint": "/api/v1/users"
        }
      ],
      "schemas": [
        {
          "connection_target": "user-service",
          "role": "request",
          "fields": [
            { "name": "user_id", "type": "string", "required": true }
          ]
        }
      ]
    }
  ]
}

Field reference

Top-level

Field	Type	Required	Description
`version`	string	yes	Payload version — currently `"1"`
`repo_name`	string	yes	Repository name (e.g., `acme-api`)
`repo_url`	string	no	Repository URL for linking
`branch`	string	no	Git branch name
`commit_sha`	string	no	Git commit SHA
`findings`	array	yes	Array of service findings

Finding

Field	Type	Required	Description
`service_name`	string	yes	Name of the detected service
`service_type`	string	no	`service`, `database`, `cache`, `broker`, `external`
`language`	string	no	Primary language
`version`	string	no	Service version
`endpoints`	array	no	Exposed endpoints
`connections`	array	no	Outbound connections to other services
`schemas`	array	no	Request/response schemas for connections

Versioning policy

Payload versions are additive only. New fields may be added without bumping the version. Removed fields get a 6-month deprecation window. The hub accepts multiple payload versions simultaneously.

Sanitization

Service names are sanitized at ingest — HTML tags, script content, null bytes, and control characters are stripped to prevent XSS in the multi-tenant dashboard.

Size limits

Maximum payload size: 5 MB. Payloads exceeding this limit receive a 413 Payload Too Large response.

Scan Payload Format