Endpoint discovery

Every database publishes a discovery document at:

GET https://api.persql.com/p/<namespace>/<database>/.well-known/endpoints.json

The shape is stable — MCP clients, code-gen agents, and the console’s Connect panel all rely on it.

Response

{
  "namespace": "acme",
  "database": "orders",
  "endpoints": [
    {
      "name": "list_orders",
      "description": "List orders for a customer",
      "input_schema": {
        "type": "object",
        "properties": {
          "customer_id": { "type": "integer" },
          "limit": { "type": "integer", "minimum": 1, "maximum": 100 }
        },
        "required": ["customer_id"]
      },
      "url": "https://api.persql.com/p/acme/orders/list-orders",
      "method": "GET"
    }
  ]
}

Each entry is endpointToToolDefinition(spec) — a JSON-Schema-shaped tool that drops directly into Anthropic / OpenAI function-calling APIs or any MCP runtime.

Only published endpoints appear. Cache-Control: public, max-age=30, Access-Control-Allow-Origin: *.

Why agents like it

If you point an agent at a single URL — <host>/.well-known/endpoints.json — it can:

1. Enumerate every callable endpoint on the database.
2. Read the input schema for each.
3. Call the right one with validated arguments.

That gives you an MCP-shaped tool surface without running an MCP server. Custom hostnames make it especially clean: api.acme.com/.well-known/endpoints.json is the entire integration contract.

OpenAPI

For a richer per-namespace contract (paths, response shapes, tags), hit:

GET https://api.persql.com/api/openapi.json

The console’s docs viewer renders it; you can also feed it to anything that consumes OpenAPI 3.1.