{"openapi":"3.1.0","info":{"title":"Netzo website API","version":"1.0.0","summary":"Machine-readable indexes and scoped access for agents","description":"Public search and discovery endpoints for netzo.io. Restricted operations require a scoped API key or bearer token.","contact":{"url":"https://netzo.io"}},"servers":[{"url":"https://netzo.io"}],"tags":[{"name":"Discovery","description":"Indexes for crawlers and agents"},{"name":"Search","description":"Public site search"},{"name":"Auth","description":"Scoped credentials"}],"paths":{"/openapi.json":{"get":{"tags":["Discovery"],"operationId":"getOpenApi","summary":"OpenAPI specification","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/llms.txt":{"get":{"tags":["Discovery"],"operationId":"getLlmsTxt","summary":"LLM-oriented site index","security":[],"responses":{"200":{"description":"llms.txt index","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/sitemap.xml":{"get":{"tags":["Discovery"],"operationId":"getSitemap","summary":"XML sitemap","security":[],"responses":{"200":{"description":"Sitemap","content":{"application/xml":{"schema":{"type":"string"}}}}}}},"/api/search.json":{"get":{"tags":["Search"],"operationId":"searchSite","summary":"Public search index","description":"Returns titles and paths for public markdown pages. Scope search:read is optional for public access and required when a credential is sent.","security":[{"ApiKeyAuth":["search:read"]},{"OAuth2":["search:read"]},{}],"responses":{"200":{"description":"Search documents","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}}},"401":{"description":"Missing or unknown credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Credential is missing search:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/health":{"get":{"tags":["Discovery"],"operationId":"getHealth","summary":"API health","security":[],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","required":["ok","name"],"properties":{"ok":{"type":"boolean"},"name":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}}}}},"/api/v1/whoami":{"get":{"tags":["Auth"],"operationId":"getWhoami","summary":"Inspect scoped credential","security":[{"ApiKeyAuth":["search:read"]},{"OAuth2":["search:read"]}],"responses":{"200":{"description":"Granted scopes","content":{"application/json":{"schema":{"type":"object","required":["authenticated","scheme","scopes"],"properties":{"authenticated":{"type":"boolean"},"scheme":{"type":"string","enum":["apiKey","bearer"]},"scopes":{"type":"array","items":{"type":"string","enum":["search:read","content:read","internal:read"]}}}}}}},"401":{"description":"Missing or unknown credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/oauth/token":{"post":{"tags":["Auth"],"operationId":"createOAuthToken","summary":"Client-credentials token","description":"Exchanges a scoped API key for a bearer token. Keys are issued by Netzo; this website does not offer public self-service signup.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string"},"client_secret":{"type":"string"},"scope":{"type":"string","description":"Space-delimited scopes"}}}}}},"responses":{"200":{"description":"Access token","content":{"application/json":{"schema":{"type":"object","required":["access_token","token_type","scope"],"properties":{"access_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"scope":{"type":"string"}}}}}},"400":{"description":"Invalid grant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Unknown client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error","code","message","resolution","status","docs"],"properties":{"error":{"type":"boolean","enum":[true]},"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"},"status":{"type":"integer"},"docs":{"type":"string","format":"uri"},"scopes":{"type":"array","items":{"type":"string","enum":["search:read","content:read","internal:read"]}}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Scoped API key. Allowed scopes: search:read, content:read, internal:read."},"OAuth2":{"type":"oauth2","description":"Client-credentials flow with least-privilege scopes.","flows":{"clientCredentials":{"tokenUrl":"https://netzo.io/api/v1/oauth/token","scopes":{"search:read":"Read the public site search index","content:read":"Read public pages, posts, and legal documents","internal:read":"Read internal documentation (restricted)"}}}}}}}