Docs and examples

Compile specs into agent-ready contracts.

Use `/v1/compile` for tool contracts, risk labels, workflow packaging guidance, and launch checklists. Use `/v1/score` for readiness checks. Send the API key in `x-alinafe-key`.

curl

curl -s https://alinafe.net/v1/compile \
  -H "content-type: application/json" \
  -H "x-alinafe-key: $ALINAFE_API_KEY" \
  -d @openapi.json

JavaScript / TypeScript

const response = await fetch("https://alinafe.net/v1/compile", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-alinafe-key": process.env.ALINAFE_API_KEY
  },
  body: JSON.stringify(openApiDocument)
});

if (!response.ok) {
  throw new Error(await response.text());
}

const { data } = await response.json();
console.log(data.mcp.tools);
console.log(data.agentExperience.launchChecklist);

Python

import json
import os
import requests

with open("openapi.json", "r", encoding="utf-8") as handle:
    spec = json.load(handle)

response = requests.post(
    "https://alinafe.net/v1/compile",
    headers={
        "content-type": "application/json",
        "x-alinafe-key": os.environ["ALINAFE_API_KEY"],
    },
    json=spec,
    timeout=30,
)
response.raise_for_status()
print(response.json()["data"]["mcp"]["tools"])

Minimal OpenAPI input

{
  "openapi": "3.1.0",
  "info": { "title": "Billing API", "version": "1.0.0" },
  "paths": {
    "/customers/{customerId}": {
      "get": {
        "operationId": "getCustomer",
        "summary": "Fetch customer billing status",
        "parameters": [
          {
            "name": "customerId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": { "200": { "description": "Customer profile" } }
      }
    }
  }
}

Claude / Codex / Cursor MCP flow

# 1. Compile your OpenAPI document.
curl -s https://alinafe.net/v1/compile \
  -H "content-type: application/json" \
  -H "x-alinafe-key: $ALINAFE_API_KEY" \
  -d @openapi.json > alinafe-tools.json

# 2. Use data.mcp.tools as the source of tool definitions.
# Use data.agentExperience to decide whether to publish tools
# directly, split them into workflow toolsets, or add progressive discovery.

# 3. Keep destructive tools gated. Alinafe labels read, write,
# and destructive operations so the host agent can apply approval rules.

Authentication

Pass your key as `x-alinafe-key`. Missing, inactive, or over-limit keys return structured JSON errors.

Agent experience output

`agentExperience` returns risk counts, packaging mode, suggested toolsets, launch checklist, and sellable readiness assets.

OpenAPI endpoint

Fetch this API's own schema from /v1/openapi for client generation or inspection.

Errors, retries, and request IDs

# Every response includes x-request-id.
# Error responses use application/problem+json and mirror
# the stable code in x-alinafe-error-code and error.code.

curl -i https://alinafe.net/v1/compile \
  -H "x-request-id: my-trace-2026-0001" \
  -H "content-type: application/json" \
  -d '{}'

# Paid checkout creation supports safe retries.
curl -s https://alinafe.net/v1/checkout \
  -H "content-type: application/json" \
  -H "Idempotency-Key: checkout-dev-example-001" \
  -d '{"email":"dev@example.com","plan":"pro"}'

Launch-readiness fields

{
  "agentExperience": {
    "riskBreakdown": {
      "read": 14,
      "write": 8,
      "sensitive_write": 2,
      "destructive": 1
    },
    "packaging": {
      "mode": "workflow-scoped-toolsets",
      "suggestedToolsets": [
        { "name": "billing", "toolCount": 12, "publishAs": "direct agent toolset" }
      ]
    },
    "launchChecklist": [
      "Declare auth scopes and approval rules before exposing write-capable tools.",
      "Gate destructive operations behind explicit human confirmation."
    ]
  }
}