Safe4AI developer resources — API, OpenAPI, OAuth 2.0, API Keys, Agent Sandbox, CLI

Quickstart

Machine-readable API discovery

The canonical Safe4AI REST contract is OpenAPI 3.1. Every operation has a unique operationId, description, typed request fields, typed response schemas, and explicit authentication requirements for agent function calling.

GET https://safe4ai.com/api GET https://safe4ai.com/openapi.json GET https://safe4ai.com/.well-known/oauth-authorization-server

Open OpenAPI spec Open API discovery Open OAuth metadata

Zero auth

Public sandbox

Use the deterministic sandbox immediately. It validates request/response plumbing and structured errors; it does not run customer data through an AI model.

curl -s https://safe4ai.com/api/v1/sandbox curl -s -X POST https://safe4ai.com/api/v1/sandbox \ -H 'Content-Type: application/json' \ -d '{"input":"hello agent"}'

JSON errors

Errors agents can act on

REST errors use JSON with a stable code, readable message, and concrete resolution hint. OAuth protocol endpoints retain their standard error and error_description fields and add remediation fields.

{ "error": { "code": "INPUT_REQUIRED", "message": "input is required...", "resolution": "Provide input in the JSON request body." } }

Self-service API key

One request to an authenticated agent endpoint

Create an expiring sandbox key without signup, billing, or a sales form. The key is sandbox-only and cannot access customer or production systems.

# 1) Create a 24-hour sandbox API key curl -s -X POST https://safe4ai.com/api/v1/keys \ -H 'Content-Type: application/json' \ -d '{"client_name":"my-agent"}' # 2) Use the returned api_key curl -s https://safe4ai.com/api/v1/agent/ping \ -H "X-API-Key: $SAFE4AI_API_KEY" curl -s -X POST https://safe4ai.com/api/v1/agent/echo \ -H "X-API-Key: $SAFE4AI_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"input":"hello from my agent"}'

OAuth 2.0

Client-credentials flow for machine-to-machine agents

Safe4AI also exposes RFC-style dynamic sandbox client registration and OAuth 2.0 client_credentials. Registration is immediate. Access tokens are short-lived and sandbox-scoped.

# 1) Register a sandbox OAuth client curl -s -X POST https://safe4ai.com/oauth/register \ -H 'Content-Type: application/json' \ -d '{"client_name":"my-agent","grant_types":["client_credentials"],"scope":"sandbox:read sandbox:write"}' # 2) Exchange client credentials for a bearer token curl -s -X POST https://safe4ai.com/oauth/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode "client_id=$SAFE4AI_CLIENT_ID" \ --data-urlencode "client_secret=$SAFE4AI_CLIENT_SECRET" \ --data-urlencode 'scope=sandbox:read sandbox:write' # 3) Call an authenticated endpoint curl -s https://safe4ai.com/api/v1/agent/ping \ -H "Authorization: Bearer $SAFE4AI_ACCESS_TOKEN"

Authorization server metadata is published at /.well-known/oauth-authorization-server. This sandbox server supports client_credentials only, so it has no browser authorization endpoint.

Function calling

Typed callable operations

Agents can import /openapi.json and map operations directly into tools. Authenticated operations accept either OAuth or X-API-Key.

GET /api/v1/agent/ping POST /api/v1/agent/echo

Content negotiation

Markdown for agents

Safe4AI public pages support Markdown content negotiation. Send Accept: text/markdown; responses vary on Accept.

curl -i -H 'Accept: text/markdown' https://safe4ai.com/services curl -i -H 'Accept: text/markdown' https://safe4ai.com/developers

CLI

Safe4AI CLI

The official Safe4AI CLI package on npm is safe4ai-cli. It verifies agent-facing HTTP contracts and calls the public sandbox.

npm install -g safe4ai-cli npx safe4ai-cli doctor npx safe4ai-cli sandbox "hello agent" npx safe4ai-cli docs

Rate limits

IETF RateLimit headers

Every Safe4AI sandbox API response includes IETF RateLimit-Policy / RateLimit fields plus compatibility X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset so agents can self-throttle. Default quota: 120 requests / 60 seconds per client IP. HTTP 429 responses include Retry-After. Agents can probe the contract with ?force_rate_limit=1.

RateLimit-Policy: "safe4ai-sandbox";q=120;w=60 RateLimit-Limit: 120 X-RateLimit-Limit: 120 Retry-After: 60 curl -i "https://safe4ai.com/api/v1/sandbox?force_rate_limit=1"

Versioning

API versioning and deprecation

The public sandbox API is versioned in the URL path (/api/v1/...). Breaking changes ship under a new major path. Deprecated operations advertise Deprecation: true and a Sunset HTTP-date at least 90 days before removal. Full policy: /developers/versioning. The unversioned /api/sandbox alias is deprecated in favor of /api/v1/sandbox.

# Current GET /api/v1/sandbox # Deprecated compatibility alias (returns Deprecation + Sunset) GET /api/sandbox

Discovery

Agent resource index

/api — public JSON API directory.
/openapi.json — OpenAPI 3.1 contract.
/api/v1/keys — self-service sandbox API key endpoint.
OAuth metadata — authorization server discovery.
/llms.txt — Safe4AI product and developer context.
/sitemap.xml — canonical public pages.
Versioning policy — Sunset / Deprecation rules.
Rate limits — IETF RateLimit header conventions.

Production boundary

Public sandbox vs. customer APIs

The endpoints documented here prove reachability, self-service onboarding, OAuth, schemas, error contracts, and function-calling compatibility without exposing customer systems. Production project credentials and business-specific APIs remain isolated per deployment.

Inspect the schema Discuss production integration