{ "openapi": "3.1.0", "info": { "title": "Safe4AI Agent API", "version": "1.4.0", "summary": "Safe4AI public sandbox API for agent integrations", "description": "Public Safe4AI sandbox and authentication endpoints for agent integrations. Sandbox operations do not process customer data with an AI model. Production/customer APIs are provisioned separately.\n\n## Versioning and deprecation\n\nThe public sandbox API is versioned in the URL path (`/api/v1/...`). Breaking changes ship under a new major path (`/api/v2/...`). Deprecated operations advertise `Deprecation: true` and a `Sunset` HTTP-date header at least 90 days before removal. See https://safe4ai.com/developers/versioning.\n\n## Rate limits\n\nSandbox endpoints advertise IETF RateLimit headers (`RateLimit-Policy`, `RateLimit`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`). The default quota is 120 requests per 60 seconds per client IP. Compatibility `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers are also returned. HTTP 429 responses include `Retry-After`. Probe with `?force_rate_limit=1` on sandbox endpoints.\n\n## Compatibility alias\n\n`GET|POST /api/sandbox` is a deprecated alias for `/api/v1/sandbox`. It returns `Deprecation: true` and a `Sunset` header. New integrations must use `/api/v1/sandbox`.", "contact": { "name": "Safe4AI Developer Support", "email": "info@safe4ai.com", "url": "https://safe4ai.com/developers" }, "license": { "name": "Documentation under site terms", "url": "https://safe4ai.com/privacy-policy" } }, "externalDocs": { "description": "Safe4AI developer resources \u2014 Quickstart, OAuth, API keys, sandbox, CLI", "url": "https://safe4ai.com/developers" }, "x-rate-limit-policy": { "name": "safe4ai-sandbox", "quota": 120, "window_seconds": 60, "partition": "client IP address", "documentation": "https://safe4ai.com/developers#rate-limits", "compatibility_headers": [ "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset", "Retry-After" ] }, "x-api-versioning": { "style": "url-path", "current": "v1", "deprecation_policy": "https://safe4ai.com/developers/versioning", "sunset_notice_days": 90 }, "servers": [ { "url": "https://safe4ai.com", "description": "Safe4AI public sandbox and authentication server" } ], "tags": [ { "name": "Discovery", "description": "Machine-readable API and authorization discovery." }, { "name": "Credentials", "description": "Self-service sandbox credentials." }, { "name": "OAuth", "description": "OAuth 2.0 client registration and client-credentials token issuance." }, { "name": "Sandbox", "description": "Zero-auth deterministic integration checks." }, { "name": "Agent", "description": "Authenticated agent integration checks." } ], "paths": { "/api": { "get": { "tags": [ "Discovery" ], "operationId": "getApiDiscovery", "summary": "Get Safe4AI API discovery", "description": "Returns a JSON directory for the Safe4AI public sandbox API, OpenAPI document, OAuth metadata, self-service credentials, documentation, rate-limit policy, versioning policy, and reachable endpoints. No authentication is required.", "security": [], "responses": { "200": { "description": "Safe4AI API discovery document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDiscovery" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "verbose", "in": "query", "required": false, "description": "Optional client flag reserved for agents; ignored by the server.", "schema": { "type": "boolean", "default": false } } ] } }, "/.well-known/oauth-authorization-server": { "get": { "tags": [ "Discovery" ], "operationId": "getOAuthAuthorizationServerMetadata", "summary": "Get OAuth 2.0 authorization server metadata", "description": "Returns RFC 8414 metadata for the Safe4AI sandbox authorization server. The server supports client_credentials only and therefore has no browser authorization endpoint.", "security": [], "responses": { "200": { "description": "OAuth 2.0 authorization server metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAuthorizationServerMetadata" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "verbose", "in": "query", "required": false, "description": "Optional client flag reserved for agents; ignored by the server.", "schema": { "type": "boolean", "default": false } } ] } }, "/api/v1/keys": { "post": { "tags": [ "Credentials" ], "operationId": "createSandboxApiKey", "summary": "Create a sandbox API key", "description": "Creates an immediately usable, expiring API key for Safe4AI sandbox agent endpoints. No prior authentication is required. The key cannot access production or customer data.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyRequest" } } } }, "responses": { "201": { "description": "Sandbox API key created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "400": { "description": "Invalid key request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Credential service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/oauth/register": { "post": { "tags": [ "OAuth" ], "operationId": "registerSandboxOAuthClient", "summary": "Register a sandbox OAuth client", "description": "Registers a sandbox OAuth client using RFC 7591-style dynamic client registration. Only client_credentials and sandbox scopes are supported.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientRegistrationRequest" } } } }, "responses": { "201": { "description": "Sandbox OAuth client registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientRegistrationResponse" } } } }, "400": { "description": "Invalid client metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthRegistrationError" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Authorization service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthRegistrationError" } } } } } } }, "/oauth/token": { "post": { "tags": [ "OAuth" ], "operationId": "createSandboxAccessToken", "summary": "Create an OAuth access token", "description": "Exchanges sandbox client credentials for a short-lived bearer token using OAuth 2.0 client_credentials. Supports client_secret_basic and client_secret_post.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" } } } }, "responses": { "200": { "description": "Bearer token created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "400": { "description": "Invalid OAuth request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }, "401": { "description": "Client authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Authorization service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } } } } }, "/api/v1/sandbox": { "get": { "tags": [ "Sandbox" ], "operationId": "getSandboxCapabilities", "summary": "Get sandbox capabilities", "description": "Returns the public sandbox contract and discovery links. No authentication is required.", "security": [], "responses": { "200": { "description": "Sandbox capability document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxCapabilities" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "verbose", "in": "query", "required": false, "description": "Optional client flag reserved for agents; ignored by the server.", "schema": { "type": "boolean", "default": false } }, { "name": "force_rate_limit", "in": "query", "required": false, "description": "When set to 1, returns HTTP 429 with Retry-After so agents can verify rate-limit handling.", "schema": { "type": "string", "enum": [ "1" ] } } ] }, "post": { "tags": [ "Sandbox" ], "operationId": "echoSandboxInput", "summary": "Echo a sandbox input", "description": "Validates JSON request/response plumbing with a deterministic echo. No authentication is required and no customer data is processed by an AI model.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EchoRequest" } } } }, "responses": { "200": { "description": "Deterministic sandbox echo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxEchoResponse" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/agent/ping": { "get": { "tags": [ "Agent" ], "operationId": "pingAuthenticatedAgent", "summary": "Ping the authenticated agent API", "description": "Verifies an OAuth bearer token or sandbox API key and returns the authenticated sandbox identity plus discovery links.", "security": [ { "Safe4AIOAuth": [ "sandbox:read" ] }, { "SandboxApiKey": [] } ], "responses": { "200": { "description": "Authenticated agent API is reachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPingResponse" } } } }, "401": { "description": "Missing, invalid, or expired credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Credential lacks sandbox:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Authorization service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "verbose", "in": "query", "required": false, "description": "Optional client flag reserved for agents; ignored by the server.", "schema": { "type": "boolean", "default": false } } ] } }, "/api/v1/agent/echo": { "post": { "tags": [ "Agent" ], "operationId": "echoAuthenticatedAgentInput", "summary": "Echo authenticated agent input", "description": "Validates authenticated agent function calling with a typed JSON request and deterministic response. This sandbox operation does not invoke an AI model.", "security": [ { "Safe4AIOAuth": [ "sandbox:write" ] }, { "SandboxApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EchoRequest" } } } }, "responses": { "200": { "description": "Authenticated deterministic echo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEchoResponse" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid, or expired credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Credential lacks sandbox:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Authorization service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sandbox": { "get": { "tags": [ "Sandbox" ], "operationId": "getDeprecatedSandboxCapabilities", "summary": "Get deprecated sandbox capabilities", "description": "Deprecated compatibility alias for /api/v1/sandbox. Returns Deprecation and Sunset headers. New integrations must call /api/v1/sandbox.", "security": [], "responses": { "200": { "description": "Sandbox capability document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxCapabilities" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "verbose", "in": "query", "required": false, "description": "Optional client flag reserved for agents; ignored by the server.", "schema": { "type": "boolean", "default": false } }, { "name": "force_rate_limit", "in": "query", "required": false, "description": "When set to 1, returns HTTP 429 with Retry-After so agents can verify rate-limit handling.", "schema": { "type": "string", "enum": [ "1" ] } } ], "deprecated": true }, "post": { "tags": [ "Sandbox" ], "operationId": "echoDeprecatedSandboxInput", "summary": "Echo via deprecated sandbox alias", "description": "Deprecated compatibility alias for /api/v1/sandbox. Returns Deprecation and Sunset headers. New integrations must call /api/v1/sandbox.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EchoRequest" } } } }, "responses": { "200": { "description": "Deterministic sandbox echo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxEchoResponse" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "deprecated": true } } }, "components": { "securitySchemes": { "Safe4AIOAuth": { "type": "oauth2", "description": "OAuth 2.0 client-credentials flow for Safe4AI sandbox agent endpoints. Register at /oauth/register.", "flows": { "clientCredentials": { "tokenUrl": "https://safe4ai.com/oauth/token", "scopes": { "sandbox:read": "Read sandbox agent resources.", "sandbox:write": "Invoke sandbox agent write/echo operations." } } } }, "SandboxApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Self-service expiring sandbox API key created at /api/v1/keys. It cannot access production/customer data." } }, "schemas": { "ErrorDetails": { "type": "object", "additionalProperties": false, "properties": { "max_length": { "type": "integer", "minimum": 1, "description": "Maximum allowed length when an input limit was exceeded." }, "field": { "type": "string", "description": "Field name that failed validation when applicable." }, "quota": { "type": "integer", "minimum": 1, "description": "Rate-limit quota when RATE_LIMIT_EXCEEDED." }, "window_seconds": { "type": "integer", "minimum": 1, "description": "Rate-limit window seconds when RATE_LIMIT_EXCEEDED." } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message", "resolution" ], "additionalProperties": false, "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "resolution": { "type": "string", "minLength": 1 }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "description": "error" } } }, "OAuthError": { "type": "object", "required": [ "error", "error_description", "error_code", "message", "resolution" ], "additionalProperties": false, "properties": { "error": { "type": "string", "minLength": 1, "description": "error" }, "error_description": { "type": "string", "minLength": 1, "description": "error description" }, "error_code": { "type": "string", "minLength": 1, "description": "error code" }, "message": { "type": "string", "minLength": 1, "description": "message" }, "resolution": { "type": "string", "minLength": 1, "description": "resolution" } } }, "OAuthRegistrationError": { "type": "object", "required": [ "error", "error_description", "error_code", "message", "resolution" ], "additionalProperties": false, "properties": { "error": { "type": "string", "enum": [ "invalid_client_metadata", "server_error" ], "description": "error" }, "error_description": { "type": "string", "minLength": 1, "description": "error description" }, "error_code": { "type": "string", "minLength": 1, "description": "error code" }, "message": { "type": "string", "minLength": 1, "description": "message" }, "resolution": { "type": "string", "minLength": 1, "description": "resolution" } } }, "ApiKeyRequest": { "type": "object", "additionalProperties": false, "properties": { "client_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Human-readable name for the integrating agent or application.", "examples": [ "research-agent" ] } } }, "ApiKeyResponse": { "type": "object", "required": [ "api_key", "key_id", "token_type", "header", "issued_at", "expires_at", "scope", "environment", "documentation_uri" ], "additionalProperties": false, "properties": { "api_key": { "type": "string", "minLength": 1, "writeOnly": true, "description": "api key" }, "key_id": { "type": "string", "minLength": 1, "description": "key id" }, "token_type": { "type": "string", "const": "ApiKey" }, "header": { "type": "string", "const": "X-API-Key" }, "issued_at": { "type": "integer", "format": "int64", "minimum": 0, "description": "issued at" }, "expires_at": { "type": "integer", "format": "int64", "minimum": 0, "description": "expires at" }, "scope": { "type": "string", "minLength": 1, "description": "scope" }, "environment": { "type": "string", "const": "sandbox" }, "documentation_uri": { "type": "string", "format": "uri", "description": "documentation uri" } } }, "OAuthAuthorizationServerMetadata": { "type": "object", "required": [ "issuer", "token_endpoint", "registration_endpoint", "grant_types_supported", "token_endpoint_auth_methods_supported", "scopes_supported", "service_documentation" ], "additionalProperties": false, "properties": { "issuer": { "type": "string", "format": "uri", "const": "https://safe4ai.com" }, "token_endpoint": { "type": "string", "format": "uri", "description": "token endpoint" }, "registration_endpoint": { "type": "string", "format": "uri", "description": "registration endpoint" }, "grant_types_supported": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "const": "client_credentials" }, "description": "grant types supported" }, "token_endpoint_auth_methods_supported": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "client_secret_basic", "client_secret_post" ] }, "description": "token endpoint auth methods supported" }, "scopes_supported": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "sandbox:read", "sandbox:write" ] }, "description": "scopes supported" }, "service_documentation": { "type": "string", "format": "uri", "description": "service documentation" } } }, "OAuthClientRegistrationRequest": { "type": "object", "additionalProperties": false, "properties": { "client_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "client name" }, "grant_types": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "const": "client_credentials" }, "examples": [ [ "client_credentials" ] ], "description": "grant types" }, "token_endpoint_auth_method": { "type": "string", "enum": [ "client_secret_basic", "client_secret_post" ], "description": "token endpoint auth method" }, "scope": { "type": "string", "minLength": 1, "examples": [ "sandbox:read sandbox:write" ], "description": "scope" } } }, "OAuthClientRegistrationResponse": { "type": "object", "required": [ "client_id", "client_secret", "client_id_issued_at", "client_secret_expires_at", "client_name", "token_endpoint_auth_method", "grant_types", "scope" ], "additionalProperties": false, "properties": { "client_id": { "type": "string", "minLength": 1, "description": "client id" }, "client_secret": { "type": "string", "minLength": 1, "writeOnly": true, "description": "client secret" }, "client_id_issued_at": { "type": "integer", "format": "int64", "minimum": 0, "description": "client id issued at" }, "client_secret_expires_at": { "type": "integer", "format": "int64", "minimum": 0, "description": "client secret expires at" }, "client_name": { "type": "string", "minLength": 1, "description": "client name" }, "token_endpoint_auth_method": { "type": "string", "enum": [ "client_secret_basic", "client_secret_post" ], "description": "token endpoint auth method" }, "grant_types": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "const": "client_credentials" }, "description": "grant types" }, "scope": { "type": "string", "minLength": 1, "description": "scope" } } }, "OAuthTokenRequest": { "type": "object", "required": [ "grant_type" ], "additionalProperties": false, "properties": { "grant_type": { "type": "string", "const": "client_credentials", "description": "OAuth grant type." }, "client_id": { "type": "string", "minLength": 1, "description": "Sandbox client identifier when using client_secret_post." }, "client_secret": { "type": "string", "minLength": 1, "writeOnly": true, "description": "Sandbox client secret when using client_secret_post." }, "scope": { "type": "string", "minLength": 1, "description": "Space-delimited requested scopes.", "examples": [ "sandbox:read sandbox:write" ] } } }, "OAuthTokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "scope" ], "additionalProperties": false, "properties": { "access_token": { "type": "string", "minLength": 1, "writeOnly": true, "description": "access token" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer", "minimum": 1, "description": "expires in" }, "scope": { "type": "string", "minLength": 1, "description": "scope" } } }, "SandboxAccepts": { "type": "object", "required": [ "content_type", "required_fields", "input_type", "input_max_length" ], "additionalProperties": false, "properties": { "content_type": { "type": "string", "const": "application/json" }, "required_fields": { "type": "array", "minItems": 1, "items": { "type": "string", "const": "input" }, "description": "required fields" }, "input_type": { "type": "string", "const": "string" }, "input_max_length": { "type": "integer", "const": 2000 } } }, "SandboxCapabilities": { "type": "object", "required": [ "environment", "service", "version", "authentication", "self_service_api_key", "oauth_authentication", "accepts", "docs", "openapi", "oauth_metadata", "rate_limit", "versioning_policy" ], "additionalProperties": false, "properties": { "environment": { "type": "string", "const": "sandbox" }, "service": { "type": "string", "minLength": 1, "description": "service" }, "version": { "type": "string", "minLength": 1, "description": "version" }, "authentication": { "type": "string", "minLength": 1, "description": "authentication" }, "self_service_api_key": { "type": "string", "minLength": 1, "description": "self service api key" }, "oauth_authentication": { "type": "string", "minLength": 1, "description": "oauth authentication" }, "accepts": { "$ref": "#/components/schemas/SandboxAccepts" }, "docs": { "type": "string", "format": "uri", "description": "docs" }, "openapi": { "type": "string", "format": "uri", "description": "openapi" }, "oauth_metadata": { "type": "string", "format": "uri", "description": "oauth metadata" }, "rate_limit": { "type": "object", "required": [ "name", "quota", "window_seconds" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 }, "quota": { "type": "integer", "minimum": 1 }, "window_seconds": { "type": "integer", "minimum": 1 } }, "description": "rate limit" }, "versioning_policy": { "type": "string", "format": "uri", "description": "versioning policy" } } }, "EchoRequest": { "type": "object", "required": [ "input" ], "additionalProperties": false, "properties": { "input": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Text used to validate request/response and function-calling plumbing.", "examples": [ "hello agent" ] } } }, "SandboxEchoResponse": { "type": "object", "required": [ "environment", "request_id", "input", "output", "note" ], "additionalProperties": false, "properties": { "environment": { "type": "string", "const": "sandbox" }, "request_id": { "type": "string", "format": "uuid", "description": "request id" }, "input": { "type": "string", "minLength": 1, "description": "input" }, "output": { "type": "string", "minLength": 1, "description": "output" }, "note": { "type": "string", "minLength": 1, "description": "note" } } }, "AgentPingResponse": { "type": "object", "required": [ "service", "environment", "status", "authenticated_client", "authentication", "scope", "documentation", "openapi" ], "additionalProperties": false, "properties": { "service": { "type": "string", "minLength": 1, "description": "service" }, "environment": { "type": "string", "const": "sandbox" }, "status": { "type": "string", "const": "ok" }, "authenticated_client": { "type": "string", "minLength": 1, "description": "authenticated client" }, "authentication": { "type": "string", "enum": [ "oauth2", "api_key" ], "description": "authentication" }, "scope": { "type": "string", "minLength": 1, "description": "scope" }, "documentation": { "type": "string", "format": "uri", "description": "documentation" }, "openapi": { "type": "string", "format": "uri", "description": "openapi" } } }, "AgentEchoResponse": { "type": "object", "required": [ "environment", "request_id", "authenticated_client", "authentication", "input", "output", "note" ], "additionalProperties": false, "properties": { "environment": { "type": "string", "const": "sandbox" }, "request_id": { "type": "string", "format": "uuid", "description": "request id" }, "authenticated_client": { "type": "string", "minLength": 1, "description": "authenticated client" }, "authentication": { "type": "string", "enum": [ "oauth2", "api_key" ], "description": "authentication" }, "input": { "type": "string", "minLength": 1, "description": "input" }, "output": { "type": "string", "minLength": 1, "description": "output" }, "note": { "type": "string", "minLength": 1, "description": "note" } } }, "ApiDiscovery": { "type": "object", "required": [ "name", "environment", "version", "status", "openapi", "documentation", "oauth_metadata", "unauthenticated_endpoint", "self_service_api_key_endpoint", "authenticated_endpoints", "rate_limit", "versioning_policy", "cli", "deprecated_endpoints" ], "additionalProperties": false, "properties": { "name": { "type": "string", "const": "Safe4AI Agent API" }, "environment": { "type": "string", "const": "public-sandbox" }, "version": { "type": "string", "minLength": 1, "description": "version" }, "status": { "type": "string", "const": "available" }, "openapi": { "type": "string", "format": "uri", "description": "openapi" }, "documentation": { "type": "string", "format": "uri", "description": "documentation" }, "oauth_metadata": { "type": "string", "format": "uri", "description": "oauth metadata" }, "unauthenticated_endpoint": { "type": "string", "format": "uri", "description": "unauthenticated endpoint" }, "self_service_api_key_endpoint": { "type": "string", "format": "uri", "description": "self service api key endpoint" }, "authenticated_endpoints": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" }, "description": "authenticated endpoints" }, "rate_limit": { "type": "object", "required": [ "name", "quota", "window_seconds", "documentation" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 }, "quota": { "type": "integer", "minimum": 1 }, "window_seconds": { "type": "integer", "minimum": 1 }, "documentation": { "type": "string", "format": "uri" }, "headers": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Rate-limit related response header names agents should read." } }, "description": "rate limit" }, "versioning_policy": { "type": "string", "format": "uri", "description": "versioning policy" }, "cli": { "type": "object", "required": [ "package", "docs", "commands" ], "additionalProperties": false, "properties": { "package": { "type": "string", "minLength": 1 }, "docs": { "type": "string", "format": "uri" }, "commands": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } }, "description": "cli" }, "deprecated_endpoints": { "type": "array", "minItems": 0, "items": { "type": "string", "format": "uri" }, "description": "Deprecated compatibility endpoints that still respond with Deprecation and Sunset headers." } } } } } }