{ "schemes": ["http"], "swagger": "2.0", "info": { "description": "Decentralized Agent Registry Network — register, discover, and resolve AI entities across a federated mesh.", "title": "Agent DNS Registry API", "contact": { "name": "Agent DNS", "url": "https://github.com/agentdns/agent-dns" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "version": "0.2.0" }, "host": "localhost:8080", "basePath": "/", "paths": { "/health": { "get": { "description": "Returns OK if the registry node is running.", "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Health check", "responses": { "200": { "description": "Health status", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/admin/developers/approve": { "post": { "description": "Approve a developer registration in restricted mode. Generates a keypair and returns the encrypted private key. Requires Bearer webhook token.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Admin" ], "summary": "Approve developer registration", "parameters": [ { "type": "string", "description": "Bearer \u003cwebhook-secret\u003e", "name": "Authorization", "in": "header", "required": true }, { "description": "Approval request with name and state", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.DeveloperApprovalRequest" } } ], "responses": { "201": { "description": "Developer approval response with encrypted private key", "schema": { "$ref": "#/definitions/models.DeveloperApprovalResponse" } }, "400": { "description": "Validation error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "409": { "description": "Developer already registered", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/categories": { "get": { "description": "Get all entity categories currently registered in the system.", "produces": [ "application/json" ], "tags": [ "Search" ], "summary": "List categories", "responses": { "200": { "description": "List of categories", "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/developers": { "post": { "description": "Register a new developer identity with name, public_key, and signature. Self-registration is disabled in restricted mode.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Developers" ], "summary": "Register a new developer", "parameters": [ { "description": "Developer registration payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.DeveloperRegistrationRequest" } } ], "responses": { "201": { "description": "developer_id and success message", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Validation error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Invalid signature", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Self-registration disabled", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "409": { "description": "Developer already registered", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/developers/{developerID}": { "get": { "description": "Retrieve a developer record by their developer_id. Falls back to gossip entries for remote developers.", "produces": [ "application/json" ], "tags": [ "Developers" ], "summary": "Get developer by ID", "parameters": [ { "type": "string", "description": "Developer ID", "name": "developerID", "in": "path", "required": true } ], "responses": { "200": { "description": "Developer record", "schema": { "$ref": "#/definitions/models.DeveloperRecord" } }, "404": { "description": "Developer not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "put": { "description": "Update a developer's profile fields. Requires Authorization header with Bearer ed25519 signature.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Developers" ], "summary": "Update developer profile", "parameters": [ { "type": "string", "description": "Developer ID", "name": "developerID", "in": "path", "required": true }, { "type": "string", "description": "Bearer ed25519:\u003cbase64sig\u003e", "name": "Authorization", "in": "header", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.DeveloperUpdateRequest" } } ], "responses": { "200": { "description": "Updated developer record", "schema": { "$ref": "#/definitions/models.DeveloperRecord" } }, "400": { "description": "Invalid request body", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Ownership verification failed", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Developer not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "description": "Deregister a developer identity. Requires Authorization header with Bearer ed25519 signature.", "produces": [ "application/json" ], "tags": [ "Developers" ], "summary": "Delete developer", "parameters": [ { "type": "string", "description": "Developer ID", "name": "developerID", "in": "path", "required": true }, { "type": "string", "description": "Bearer ed25519:\u003cbase64sig\u003e", "name": "Authorization", "in": "header", "required": true } ], "responses": { "200": { "description": "Deregistration confirmation", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Ownership verification failed", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Developer not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/developers/{developerID}/entities": { "get": { "description": "Retrieve all entities registered by a developer. Alias: GET /v1/developers/{id}/agents.", "produces": [ "application/json" ], "tags": [ "Developers" ], "summary": "List entities by developer", "parameters": [ { "type": "string", "description": "Developer ID", "name": "developerID", "in": "path", "required": true } ], "responses": { "200": { "description": "developer_id, entities, and count", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Missing developer_id", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/entities": { "get": { "description": "List all registered entities. Filter by type (agent, service) and category. Supports pagination.", "produces": [ "application/json" ], "tags": [ "Entities" ], "summary": "List entities", "parameters": [ { "type": "string", "description": "Filter by type: agent, service (default: all)", "name": "type", "in": "query" }, { "type": "string", "description": "Filter by category", "name": "category", "in": "query" }, { "type": "integer", "description": "Max results (default 50)", "name": "limit", "in": "query" }, { "type": "integer", "description": "Pagination offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of entities", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "description": "Register an entity. Set type to \"service\" for services (entity_url not required). Alias: POST /v1/entities, POST /v1/services.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Entities" ], "summary": "Register a new entity", "parameters": [ { "description": "Entity registration payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.RegistrationRequest" } } ], "responses": { "201": { "description": "entity_id and success message", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Validation error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Invalid signature", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "409": { "description": "Entity already registered", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/entities/{entityID}": { "get": { "description": "Retrieve a registry record for a specific entity. Alias: GET /v1/entities/{id}, GET /v1/entities/{id}.", "produces": [ "application/json" ], "tags": [ "Entities" ], "summary": "Get entity by ID", "parameters": [ { "type": "string", "description": "Entity ID (e.g. zns:7f3a9c2e... or zns:svc:7f3a9c2e...)", "name": "entityID", "in": "path", "required": true } ], "responses": { "200": { "description": "Entity registry record", "schema": { "$ref": "#/definitions/models.RegistryRecord" } }, "400": { "description": "Missing ID", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Entity not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "put": { "description": "Update fields on an existing entity. Only provided fields are changed. Alias: PUT /v1/entities/{id}.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Entities" ], "summary": "Update an entity", "parameters": [ { "type": "string", "description": "Entity ID", "name": "entityID", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.UpdateRequest" } } ], "responses": { "200": { "description": "Updated entity record", "schema": { "$ref": "#/definitions/models.RegistryRecord" } }, "400": { "description": "Invalid request body", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Entity not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "description": "Deregister an entity. Creates a tombstone that propagates via gossip. Alias: DELETE /v1/entities/{id}.", "produces": [ "application/json" ], "tags": [ "Entities" ], "summary": "Delete an entity", "parameters": [ { "type": "string", "description": "Entity ID", "name": "entityID", "in": "path", "required": true } ], "responses": { "200": { "description": "Deregistration confirmation", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Missing ID", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Entity not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/entities/{entityID}/card": { "get": { "description": "Fetch the live card from the entity's endpoint. Contains capabilities, pricing, status, and more. Alias: GET /v1/entities/{id}/card.", "produces": [ "application/json" ], "tags": [ "Entities" ], "summary": "Get entity card", "parameters": [ { "type": "string", "description": "Entity ID", "name": "entityID", "in": "path", "required": true } ], "responses": { "200": { "description": "Entity card", "schema": { "$ref": "#/definitions/models.EntityCard" } }, "400": { "description": "Missing ID", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Entity not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "502": { "description": "Failed to fetch card from remote", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/handles": { "post": { "description": "Claim a ZNS developer handle. Requires an existing developer identity and a valid signature.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Handles" ], "summary": "Claim a handle", "parameters": [ { "description": "Handle claim payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.HandleClaimRequest" } } ], "responses": { "201": { "description": "handle, developer_id, and success message", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Validation error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Invalid signature", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Developer not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "409": { "description": "Handle already taken", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/handles/{handle}": { "get": { "description": "Retrieve the developer record associated with a ZNS handle, including verification status.", "produces": [ "application/json" ], "tags": [ "Handles" ], "summary": "Get developer by handle", "parameters": [ { "type": "string", "description": "ZNS handle (e.g. alice)", "name": "handle", "in": "path", "required": true } ], "responses": { "200": { "description": "handle, developer_id, developer_name, verified, verification_method", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Missing handle", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Handle not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "description": "Release a previously claimed ZNS handle. Requires Authorization header with Bearer ed25519 signature.", "produces": [ "application/json" ], "tags": [ "Handles" ], "summary": "Release a handle", "parameters": [ { "type": "string", "description": "ZNS handle to release", "name": "handle", "in": "path", "required": true }, { "type": "string", "description": "Bearer ed25519:\u003cbase64sig\u003e", "name": "Authorization", "in": "header", "required": true } ], "responses": { "200": { "description": "Release confirmation", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Missing handle", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Ownership verification failed", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Handle not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/handles/{handle}/available": { "get": { "description": "Check whether a ZNS handle is available on this registry. Returns availability and optional reason if taken.", "produces": [ "application/json" ], "tags": [ "Handles" ], "summary": "Check handle availability", "parameters": [ { "type": "string", "description": "ZNS handle to check", "name": "handle", "in": "path", "required": true } ], "responses": { "200": { "description": "handle, available, and optional reason", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Missing handle", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/handles/{handle}/entities": { "get": { "description": "List all ZNS name bindings (entity names) registered under a given developer handle.", "produces": [ "application/json" ], "tags": [ "Handles" ], "summary": "List entities for a handle", "parameters": [ { "type": "string", "description": "ZNS developer handle", "name": "handle", "in": "path", "required": true } ], "responses": { "200": { "description": "List of ZNS name bindings", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.ZNSName" } } }, "400": { "description": "Missing handle", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/handles/{handle}/verify": { "post": { "description": "Verify a ZNS handle ownership via DNS TXT record or GitHub. Sets the verified flag and verification method on success.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Handles" ], "summary": "Verify a handle", "parameters": [ { "type": "string", "description": "ZNS handle to verify", "name": "handle", "in": "path", "required": true }, { "description": "Verification method and proof", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.HandleVerifyRequest" } } ], "responses": { "200": { "description": "Verification confirmation", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Verification failed or invalid method", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Handle not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/names": { "post": { "description": "Register a ZNS entity name binding, creating a Fully Qualified Agent Name (FQAN) under a developer handle.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Names" ], "summary": "Register an entity name", "parameters": [ { "description": "Name binding payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.NameBindingRequest" } } ], "responses": { "201": { "description": "fqan, entity_id, and success message", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Validation error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Invalid signature", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Developer handle or entity not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "409": { "description": "Name already registered", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/names/{developer}/{entity}": { "get": { "description": "Retrieve a ZNS name binding record by developer handle and entity name path parameters.", "produces": [ "application/json" ], "tags": [ "Names" ], "summary": "Get name binding", "parameters": [ { "type": "string", "description": "Developer handle", "name": "developer", "in": "path", "required": true }, { "type": "string", "description": "Entity name", "name": "entity", "in": "path", "required": true } ], "responses": { "200": { "description": "ZNS name binding", "schema": { "$ref": "#/definitions/models.ZNSName" } }, "400": { "description": "Missing path parameters", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Name not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "put": { "description": "Update the version and/or capability_tags of an existing ZNS entity name binding.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Names" ], "summary": "Update name binding", "parameters": [ { "type": "string", "description": "Developer handle", "name": "developer", "in": "path", "required": true }, { "type": "string", "description": "Entity name", "name": "entity", "in": "path", "required": true }, { "description": "Fields to update (version, capability_tags, signature)", "name": "body", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Updated ZNS name binding", "schema": { "$ref": "#/definitions/models.ZNSName" } }, "400": { "description": "Invalid request body", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Name not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "description": "Release a ZNS entity name binding. Requires Authorization header with Bearer ed25519 signature.", "produces": [ "application/json" ], "tags": [ "Names" ], "summary": "Release a name binding", "parameters": [ { "type": "string", "description": "Developer handle", "name": "developer", "in": "path", "required": true }, { "type": "string", "description": "Entity name", "name": "entity", "in": "path", "required": true }, { "type": "string", "description": "Bearer ed25519:\u003cbase64sig\u003e", "name": "Authorization", "in": "header", "required": true } ], "responses": { "200": { "description": "Release confirmation", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Ownership verification failed", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Name or developer not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/names/{developer}/{entity}/available": { "get": { "description": "Check whether a ZNS entity name is available under a given developer handle.", "produces": [ "application/json" ], "tags": [ "Names" ], "summary": "Check name availability", "parameters": [ { "type": "string", "description": "Developer handle", "name": "developer", "in": "path", "required": true }, { "type": "string", "description": "Entity name", "name": "entity", "in": "path", "required": true } ], "responses": { "200": { "description": "developer, entity_name, available, and optional reason", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Missing path parameters", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/names/{developer}/{entity}/versions": { "get": { "description": "Retrieve the full version history for a ZNS entity name binding.", "produces": [ "application/json" ], "tags": [ "Names" ], "summary": "List version history", "parameters": [ { "type": "string", "description": "Developer handle", "name": "developer", "in": "path", "required": true }, { "type": "string", "description": "Entity name", "name": "entity", "in": "path", "required": true } ], "responses": { "200": { "description": "List of version records", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.ZNSVersion" } } }, "404": { "description": "Name not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/network/peers": { "get": { "description": "Returns a list of all connected peer registries in the mesh network.", "produces": [ "application/json" ], "tags": [ "Network" ], "summary": "List peers", "responses": { "200": { "description": "Connected peers", "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/definitions/models.PeerInfo" } } } } } }, "post": { "description": "Manually add a peer registry node to the mesh network. Requires at minimum the peer's address.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Network" ], "summary": "Add a peer", "parameters": [ { "description": "Peer information", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.PeerInfo" } } ], "responses": { "201": { "description": "Peer added confirmation", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Invalid request or missing address", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/network/stats": { "get": { "description": "Returns estimated global network statistics including registry and entity counts.", "produces": [ "application/json" ], "tags": [ "Network" ], "summary": "Get network stats", "responses": { "200": { "description": "Network statistics", "schema": { "$ref": "#/definitions/models.NetworkStats" } } } } }, "/v1/network/status": { "get": { "description": "Returns the current registry node's identity, uptime, peer count, and entity statistics.", "produces": [ "application/json" ], "tags": [ "Network" ], "summary": "Get node status", "responses": { "200": { "description": "Node status", "schema": { "$ref": "#/definitions/models.NetworkStatus" } } } } }, "/v1/resolve/{developer}/{entity}": { "get": { "description": "Resolve a Fully Qualified Agent Name (FQAN) to its entity details, including entity_url, public_key, and trust information.", "produces": [ "application/json" ], "tags": [ "Resolution" ], "summary": "Resolve a FQAN", "parameters": [ { "type": "string", "description": "Developer handle", "name": "developer", "in": "path", "required": true }, { "type": "string", "description": "Entity name", "name": "entity", "in": "path", "required": true } ], "responses": { "200": { "description": "Resolved entity details", "schema": { "$ref": "#/definitions/models.ZNSResolveResponse" } }, "400": { "description": "Missing path parameters", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Name not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/search": { "post": { "description": "Search the registry for entities by natural language query, with optional category/tag/trust filters.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Search" ], "summary": "Search for entities", "parameters": [ { "description": "Search query and filters", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.SearchRequest" } } ], "responses": { "200": { "description": "Search results", "schema": { "$ref": "#/definitions/models.SearchResponse" } }, "400": { "description": "Invalid request or missing query", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Search failed", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/tags": { "get": { "description": "Get all entity tags currently in use across registered entities.", "produces": [ "application/json" ], "tags": [ "Search" ], "summary": "List tags", "responses": { "200": { "description": "List of tags", "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "definitions": { "models.EntityCard": { "type": "object", "properties": { "entity_id": { "type": "string" }, "capabilities": { "type": "array", "items": { "$ref": "#/definitions/models.Capability" } }, "endpoints": { "$ref": "#/definitions/models.Endpoints" }, "last_heartbeat": { "type": "string" }, "metadata": { "$ref": "#/definitions/models.CardMeta" }, "pricing": { "$ref": "#/definitions/models.Pricing" }, "schema_version": { "type": "string" }, "signature": { "type": "string" }, "signed_at": { "type": "string" }, "status": { "description": "online, offline, degraded, maintenance", "type": "string" }, "trust": { "$ref": "#/definitions/models.TrustInfo" }, "version": { "type": "string" } } }, "models.Capability": { "type": "object", "properties": { "description": { "type": "string" }, "examples": { "type": "array", "items": { "$ref": "#/definitions/models.Example" } }, "input_schema": { "type": "object", "additionalProperties": true }, "languages": { "description": "programming languages supported", "type": "array", "items": { "type": "string" } }, "latency_p95_ms": { "type": "integer" }, "name": { "type": "string" }, "output_schema": { "type": "object", "additionalProperties": true }, "protocols": { "description": "a2a, mcp, jsonrpc", "type": "array", "items": { "type": "string" } } } }, "models.CapabilitySummary": { "type": "object", "properties": { "input_types": { "description": "e.g., [\"text\", \"code\", \"image\"]", "type": "array", "items": { "type": "string" } }, "languages": { "description": "e.g., [\"python\", \"javascript\", \"go\"]", "type": "array", "items": { "type": "string" } }, "models": { "description": "e.g., [\"gpt-4\", \"claude-3.5-sonnet\"]", "type": "array", "items": { "type": "string" } }, "output_types": { "description": "e.g., [\"text\", \"json\", \"markdown\"]", "type": "array", "items": { "type": "string" } }, "protocols": { "description": "e.g., [\"a2a\", \"mcp\", \"jsonrpc\"]", "type": "array", "items": { "type": "string" } }, "skills": { "description": "e.g., [\"code-review\", \"linting\", \"security-audit\"]", "type": "array", "items": { "type": "string" } } } }, "models.CardMeta": { "type": "object", "properties": { "documentation": { "type": "string" }, "framework": { "type": "string" }, "model": { "type": "string" }, "owner_contact": { "type": "string" }, "source_code": { "type": "string" } } }, "models.DeveloperApprovalRequest": { "type": "object", "properties": { "callback_port": { "description": "optional — only used by CLI flow", "type": "integer" }, "metadata": { "description": "org-specific (email, kyc_id, etc.)", "type": "object", "additionalProperties": { "type": "string" } }, "name": { "type": "string" }, "state": { "description": "used to encrypt private key", "type": "string" } } }, "models.DeveloperApprovalResponse": { "type": "object", "properties": { "developer_id": { "type": "string" }, "private_key_enc": { "description": "AES-GCM encrypted with SHA256(state)", "type": "string" }, "public_key": { "description": "ed25519:\u003cbase64\u003e — for org-side key custody", "type": "string" } } }, "models.DeveloperProof": { "type": "object", "properties": { "entity_index": { "description": "derivation index", "type": "integer" }, "developer_public_key": { "description": "ed25519:\u003cbase64\u003e", "type": "string" }, "developer_signature": { "description": "ed25519:\u003cbase64\u003e over (agent_pub || index)", "type": "string" } } }, "models.DeveloperRecord": { "type": "object", "properties": { "dev_handle": { "description": "ZNS handle fields (optional — developers can exist without handles)", "type": "string" }, "dev_handle_verified": { "description": "true if handle is domain/github verified", "type": "boolean" }, "developer_id": { "description": "agdns:dev:\u003chash\u003e", "type": "string" }, "github": { "description": "optional GitHub handle", "type": "string" }, "home_registry": { "description": "registry where first registered", "type": "string" }, "name": { "description": "human-readable developer name", "type": "string" }, "profile_url": { "description": "optional website/profile", "type": "string" }, "public_key": { "description": "ed25519:\u003cbase64\u003e", "type": "string" }, "registered_at": { "type": "string" }, "schema_version": { "description": "schema version", "type": "string" }, "signature": { "description": "developer signs the registration", "type": "string" }, "updated_at": { "type": "string" }, "verification_method": { "description": "\"dns\", \"github\", or \"\" (self-claimed)", "type": "string" }, "verification_proof": { "description": "domain name or github username", "type": "string" } } }, "models.DeveloperRegistrationRequest": { "type": "object", "required": [ "name", "public_key", "signature" ], "properties": { "github": { "type": "string" }, "handle": { "description": "optional ZNS handle, claimed atomically during registration", "type": "string" }, "name": { "type": "string", "maxLength": 100, "minLength": 1 }, "profile_url": { "type": "string" }, "public_key": { "type": "string" }, "signature": { "type": "string" } } }, "models.DeveloperUpdateRequest": { "type": "object", "required": [ "signature" ], "properties": { "github": { "type": "string" }, "name": { "type": "string" }, "profile_url": { "type": "string" }, "signature": { "type": "string" } } }, "models.Endpoints": { "type": "object", "properties": { "health": { "type": "string" }, "invoke": { "type": "string" }, "websocket": { "type": "string" } } }, "models.Example": { "type": "object", "properties": { "input": { "type": "string" }, "output": { "type": "string" } } }, "models.HandleClaimRequest": { "type": "object", "required": [ "developer_id", "handle", "public_key", "signature" ], "properties": { "developer_id": { "type": "string" }, "handle": { "type": "string" }, "public_key": { "type": "string" }, "signature": { "type": "string" } } }, "models.HandleVerifyRequest": { "type": "object", "required": [ "method", "proof" ], "properties": { "method": { "description": "\"dns\" or \"github\"", "type": "string" }, "proof": { "description": "domain name or github username", "type": "string" } } }, "models.NameBindingRequest": { "type": "object", "required": [ "entity_id", "entity_name", "developer_handle", "signature" ], "properties": { "entity_id": { "type": "string" }, "entity_name": { "type": "string" }, "capability_tags": { "type": "array", "items": { "type": "string" } }, "developer_handle": { "type": "string" }, "signature": { "type": "string" }, "version": { "type": "string" } } }, "models.NetworkStats": { "type": "object", "properties": { "estimated_agents": { "type": "integer" }, "estimated_registries": { "type": "integer" }, "gossip_messages_per_hour": { "type": "integer" }, "mesh_connectivity": { "description": "0-1, estimated", "type": "number" }, "searches_per_hour": { "type": "integer" } } }, "models.NetworkStatus": { "type": "object", "properties": { "cached_cards": { "type": "integer" }, "gossip_entries": { "type": "integer" }, "local_agents": { "type": "integer" }, "name": { "type": "string" }, "node_type": { "description": "full, light, gateway", "type": "string" }, "peer_count": { "type": "integer" }, "registry_id": { "type": "string" }, "uptime": { "type": "string" }, "version": { "type": "string" } } }, "models.PeerInfo": { "type": "object", "properties": { "address": { "type": "string" }, "agent_count": { "type": "integer" }, "bloom_filter": { "description": "tags/categories bloom filter", "type": "array", "items": { "type": "integer" } }, "connected_at": { "type": "string" }, "last_seen": { "type": "string" }, "latency_ms": { "description": "last measured latency", "type": "integer" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "registry_host": { "description": "ZNS: the peer's domain name (e.g., \"dns01.zynd.ai\")", "type": "string" }, "registry_id": { "type": "string" } } }, "models.Pricing": { "type": "object", "properties": { "currency": { "type": "string" }, "model": { "description": "per-request, subscription, free", "type": "string" }, "payment_methods": { "description": "x402, stripe, lightning", "type": "array", "items": { "type": "string" } }, "rates": { "type": "object", "additionalProperties": { "type": "number", "format": "float64" } } } }, "models.PricingModel": { "type": "object", "properties": { "base_price": { "type": "number" }, "currency": { "description": "USD, USDC", "type": "string" }, "details": { "type": "string" }, "type": { "description": "free, per-call, subscription, usage-based", "type": "string" }, "unit": { "description": "request, token, month", "type": "string" } } }, "models.RegistrationRequest": { "type": "object", "required": [ "category", "name", "public_key", "signature", "summary" ], "properties": { "entity_name": { "description": "ZNS naming fields (optional — requires developer with claimed handle)", "type": "string" }, "capability_summary": { "$ref": "#/definitions/models.CapabilitySummary" }, "category": { "type": "string", "maxLength": 50, "minLength": 1 }, "developer_id": { "description": "Developer identity fields", "type": "string" }, "developer_proof": { "$ref": "#/definitions/models.DeveloperProof" }, "entity_url": { "type": "string" }, "name": { "type": "string", "maxLength": 100, "minLength": 1 }, "openapi_url": { "type": "string" }, "pricing_model": { "$ref": "#/definitions/models.PricingModel" }, "public_key": { "type": "string" }, "service_endpoint": { "type": "string" }, "signature": { "type": "string" }, "summary": { "type": "string", "maxLength": 200 }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "type": { "description": "Entity type: \"agent\" (default) or \"service\"", "type": "string" }, "version": { "description": "semver, e.g., \"2.1.0\"", "type": "string" } } }, "models.RegistryRecord": { "type": "object", "properties": { "entity_id": { "type": "string" }, "entity_index": { "type": "integer" }, "capability_summary": { "$ref": "#/definitions/models.CapabilitySummary" }, "category": { "type": "string" }, "codebase_hash": { "description": "Codebase integrity", "type": "string" }, "developer_id": { "description": "Developer identity fields", "type": "string" }, "developer_proof": { "description": "stored as JSONB", "allOf": [ { "$ref": "#/definitions/models.DeveloperProof" } ] }, "entity_url": { "type": "string" }, "home_registry": { "type": "string" }, "last_heartbeat": { "type": "string" }, "name": { "type": "string" }, "openapi_url": { "type": "string" }, "owner": { "type": "string" }, "pricing_model": { "description": "stored as JSONB", "allOf": [ { "$ref": "#/definitions/models.PricingModel" } ] }, "public_key": { "type": "string" }, "registered_at": { "type": "string" }, "schema_version": { "type": "string" }, "service_endpoint": { "type": "string" }, "signature": { "type": "string" }, "status": { "description": "Heartbeat liveness fields (server-managed, excluded from signing)", "type": "string" }, "summary": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "ttl": { "type": "integer" }, "type": { "description": "Entity type: \"agent\" (default) or \"service\"", "type": "string" }, "updated_at": { "type": "string" } } }, "models.ScoreBreakdown": { "type": "object", "properties": { "availability": { "type": "number" }, "freshness": { "type": "number" }, "semantic_similarity": { "type": "number" }, "text_relevance": { "type": "number" }, "trust_score": { "type": "number" } } }, "models.SearchRequest": { "type": "object", "properties": { "category": { "type": "string" }, "developer_handle": { "description": "filter by developer handle", "type": "string" }, "developer_id": { "description": "filter by developer", "type": "string" }, "enrich": { "type": "boolean" }, "federated": { "type": "boolean" }, "fqan": { "description": "filter by exact FQAN", "type": "string" }, "languages": { "description": "e.g., [\"python\", \"javascript\"]", "type": "array", "items": { "type": "string" } }, "max_results": { "type": "integer" }, "min_trust_score": { "type": "number" }, "models": { "description": "e.g., [\"gpt-4\"]", "type": "array", "items": { "type": "string" } }, "offset": { "type": "integer" }, "protocols": { "description": "e.g., [\"a2a\", \"mcp\"]", "type": "array", "items": { "type": "string" } }, "query": { "type": "string" }, "skills": { "description": "Capability filters", "type": "array", "items": { "type": "string" } }, "status": { "description": "online, offline, any", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "timeout_ms": { "type": "integer" }, "type": { "description": "\"agent\", \"service\", or \"\" (any)", "type": "string" } } }, "models.SearchResponse": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "offset": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/definitions/models.SearchResult" } }, "search_stats": { "$ref": "#/definitions/models.SearchStats" }, "total_found": { "type": "integer" } } }, "models.SearchResult": { "type": "object", "properties": { "entity_id": { "type": "string" }, "capability_summary": { "$ref": "#/definitions/models.CapabilitySummary" }, "card": { "description": "included if enrich=true", "allOf": [ { "$ref": "#/definitions/models.EntityCard" } ] }, "category": { "type": "string" }, "developer_handle": { "type": "string" }, "developer_id": { "type": "string" }, "fqan": { "description": "ZNS fields (populated when entity has a name binding)", "type": "string" }, "home_registry": { "type": "string" }, "name": { "type": "string" }, "openapi_url": { "type": "string" }, "score": { "type": "number" }, "score_breakdown": { "$ref": "#/definitions/models.ScoreBreakdown" }, "service_endpoint": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "type": { "description": "Entity type", "type": "string" } } }, "models.SearchStats": { "type": "object", "properties": { "federated_results": { "type": "integer" }, "gossip_results": { "type": "integer" }, "latency_ms": { "type": "integer" }, "local_results": { "type": "integer" }, "peers_queried": { "type": "integer" } } }, "models.TrustInfo": { "type": "object", "properties": { "avg_rating": { "type": "number" }, "success_rate": { "type": "number" }, "total_invocations": { "type": "integer" }, "uptime_30d": { "type": "number" }, "verifications": { "type": "array", "items": { "$ref": "#/definitions/models.Verification" } } } }, "models.UpdateRequest": { "type": "object", "required": [ "signature" ], "properties": { "capability_summary": { "$ref": "#/definitions/models.CapabilitySummary" }, "category": { "type": "string" }, "codebase_hash": { "type": "string" }, "entity_url": { "type": "string" }, "name": { "type": "string" }, "signature": { "type": "string" }, "summary": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "ttl": { "type": "integer" } } }, "models.Verification": { "type": "object", "properties": { "issued": { "type": "string" }, "issuer": { "type": "string" }, "type": { "type": "string" } } }, "models.ZNSName": { "type": "object", "properties": { "entity_id": { "description": "agdns:\u003chash\u003e", "type": "string" }, "entity_name": { "description": "e.g., \"doc-translator\"", "type": "string" }, "capability_tags": { "description": "stored as TEXT[]", "type": "array", "items": { "type": "string" } }, "current_version": { "type": "string" }, "developer_handle": { "description": "e.g., \"acme-corp\"", "type": "string" }, "developer_id": { "description": "agdns:dev:\u003chash\u003e", "type": "string" }, "fqan": { "description": "PRIMARY KEY", "type": "string" }, "registered_at": { "type": "string" }, "registry_host": { "description": "e.g., \"dns01.zynd.ai\"", "type": "string" }, "signature": { "type": "string" }, "updated_at": { "type": "string" } } }, "models.ZNSResolveResponse": { "type": "object", "properties": { "entity_id": { "type": "string" }, "developer_handle": { "type": "string" }, "developer_id": { "type": "string" }, "entity_url": { "type": "string" }, "fqan": { "type": "string" }, "protocols": { "type": "array", "items": { "type": "string" } }, "public_key": { "type": "string" }, "registry_host": { "type": "string" }, "status": { "type": "string" }, "trust_score": { "type": "number" }, "verification_tier": { "type": "string" }, "version": { "type": "string" } } }, "models.ZNSVersion": { "type": "object", "properties": { "entity_id": { "description": "entity_id at this version", "type": "string" }, "build_hash": { "type": "string" }, "fqan": { "type": "string" }, "registered_at": { "type": "string" }, "signature": { "type": "string" }, "version": { "type": "string" } } } } }