{"openapi":"3.1.0","info":{"title":"Aigon MCP over HTTP","version":"1.0.4","description":"The same registry the MCP tools expose, over ordinary HTTP, behind one dispatch path — so a namespace added later appears on both at once.\n\nThis spec is thin ON PURPOSE. Namespaces are gated per user and their functions are discovered live, so enumerating them here would be wrong for most callers. Use GET /rest/help to walk namespaces, functions and signatures, and GET /rest/skill/{namespace}/how_it_works to learn what an agent is and how anything gets into it.\n\nNO BACKWARDS COMPATIBILITY. NONE. Never hard-code an integration against this surface. Field names, response shapes and defaults can change under you at any time and without notice — including in a PATCH release, which is not a version signal here. There is no deprecation window, no versioned schema and no guarantee of any kind.\n\nWhat this means in practice: a human or an LLM must be in the loop, either composing the calls or reading the outputs. Code that parses a fixed shape unattended WILL break, and will do so silently. Read the shape at call time (GET /rest/help/{namespace}/{function}). If you need a contract that holds still, use the product's own REST API; this is not that.\n\nIt is a MIRROR of the MCP tools — same registry, same dispatch, same functions — offered over plain HTTP for the times MCP is not practical. The common one: an LLM that can run curl but cannot speak MCP at all (several hosted assistants on their cheaper plans). Also downloading an attachment, or piping JSON into a script.\n\nAuth is a bearer token: an OAuth access token, the account's API token, or a short-lived one from call('admin', 'mint_rest_token')."},"servers":[{"url":"https://mcp.aigon.ai"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"OAuth, API or minted REST token"}}},"security":[{"bearerAuth":[]}],"paths":{"/rest":{"get":{"summary":"What the sub-surfaces are","description":"Start here.\n\nAlso answers the HTTP QUERY method, taking the same parameters in an optional JSON body (a body value wins). QUERY is not expressible in OpenAPI 3.1, so it is not listed as an operation.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"What the sub-surfaces are","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed request, or arguments this function will not take"},"401":{"description":"No usable bearer token"},"403":{"description":"Authenticated, but not entitled to this"},"404":{"description":"No such namespace, function or skill — INCLUDING one hidden from this caller. Gating answers 404 rather than 403, so it cannot confirm that something exists."},"413":{"description":"Response exceeded the byte limit"},"500":{"description":"The function raised"}}}},"/rest/docs":{"get":{"summary":"This spec, rendered for a human","description":"A page that fetches openapi.json in the browser and renders it. No token. /rest/help and /rest/skill likewise answer HTML to a browser (Accept: text/html) — the public catalogue of namespaces and functions, as opposed to the per-account text a program gets.","security":[],"responses":{"200":{"description":"HTML","content":{"text/html":{}}}}}},"/rest/openapi.json":{"get":{"summary":"This document","description":"Unauthenticated: no user data is in it, and a client that must authenticate before it can learn how to authenticate is a worse client.","security":[],"responses":{"200":{"description":"This document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/rest/whoami":{"get":{"summary":"Who you are, what you can reach, and which server is answering","description":"Worth calling first: it answers what otherwise gets discovered by failing — which account, which namespaces (gated per user), and whether this server is new enough to have the function you want.\n\nAlso answers the HTTP QUERY method, taking the same parameters in an optional JSON body (a body value wins). QUERY is not expressible in OpenAPI 3.1, so it is not listed as an operation.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Who you are, what you can reach, and which server is answering","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed request, or arguments this function will not take"},"401":{"description":"No usable bearer token"},"403":{"description":"Authenticated, but not entitled to this"},"404":{"description":"No such namespace, function or skill — INCLUDING one hidden from this caller. Gating answers 404 rather than 403, so it cannot confirm that something exists."},"413":{"description":"Response exceeded the byte limit"},"500":{"description":"The function raised"}}}},"/rest/help":{"get":{"summary":"Namespaces available to this caller","description":"Gated on the notes the caller owns, so the list differs per user.\n\nAlso answers the HTTP QUERY method, taking the same parameters in an optional JSON body (a body value wins). QUERY is not expressible in OpenAPI 3.1, so it is not listed as an operation.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Namespaces available to this caller","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed request, or arguments this function will not take"},"401":{"description":"No usable bearer token"},"403":{"description":"Authenticated, but not entitled to this"},"404":{"description":"No such namespace, function or skill — INCLUDING one hidden from this caller. Gating answers 404 rather than 403, so it cannot confirm that something exists."},"413":{"description":"Response exceeded the byte limit"},"500":{"description":"The function raised"}}}},"/rest/help/{namespace}":{"get":{"summary":"Functions in a namespace","description":"\n\nAlso answers the HTTP QUERY method, taking the same parameters in an optional JSON body (a body value wins). QUERY is not expressible in OpenAPI 3.1, so it is not listed as an operation.","security":[{"bearerAuth":[]}],"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"},"description":"One of the names GET /rest/help returned for THIS caller"}],"responses":{"200":{"description":"Functions in a namespace","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed request, or arguments this function will not take"},"401":{"description":"No usable bearer token"},"403":{"description":"Authenticated, but not entitled to this"},"404":{"description":"No such namespace, function or skill — INCLUDING one hidden from this caller. Gating answers 404 rather than 403, so it cannot confirm that something exists."},"413":{"description":"Response exceeded the byte limit"},"500":{"description":"The function raised"}}}},"/rest/help/{namespace}/{function}":{"get":{"summary":"Signature and documentation for one function","description":"The authoritative description of what to put in a call body.\n\nAlso answers the HTTP QUERY method, taking the same parameters in an optional JSON body (a body value wins). QUERY is not expressible in OpenAPI 3.1, so it is not listed as an operation.","security":[{"bearerAuth":[]}],"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"},"description":""},{"name":"function","in":"path","required":true,"schema":{"type":"string"},"description":""},{"name":"examples","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include the EXAMPLES section."}],"responses":{"200":{"description":"Signature and documentation for one function","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed request, or arguments this function will not take"},"401":{"description":"No usable bearer token"},"403":{"description":"Authenticated, but not entitled to this"},"404":{"description":"No such namespace, function or skill — INCLUDING one hidden from this caller. Gating answers 404 rather than 403, so it cannot confirm that something exists."},"413":{"description":"Response exceeded the byte limit"},"500":{"description":"The function raised"}}}},"/rest/skill":{"get":{"summary":"Skill namespaces","description":"\n\nAlso answers the HTTP QUERY method, taking the same parameters in an optional JSON body (a body value wins). QUERY is not expressible in OpenAPI 3.1, so it is not listed as an operation.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Skill namespaces","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed request, or arguments this function will not take"},"401":{"description":"No usable bearer token"},"403":{"description":"Authenticated, but not entitled to this"},"404":{"description":"No such namespace, function or skill — INCLUDING one hidden from this caller. Gating answers 404 rather than 403, so it cannot confirm that something exists."},"413":{"description":"Response exceeded the byte limit"},"500":{"description":"The function raised"}}}},"/rest/skill/{namespace}":{"get":{"summary":"Skills in a namespace","description":"\n\nAlso answers the HTTP QUERY method, taking the same parameters in an optional JSON body (a body value wins). QUERY is not expressible in OpenAPI 3.1, so it is not listed as an operation.","security":[{"bearerAuth":[]}],"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"},"description":""}],"responses":{"200":{"description":"Skills in a namespace","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed request, or arguments this function will not take"},"401":{"description":"No usable bearer token"},"403":{"description":"Authenticated, but not entitled to this"},"404":{"description":"No such namespace, function or skill — INCLUDING one hidden from this caller. Gating answers 404 rather than 403, so it cannot confirm that something exists."},"413":{"description":"Response exceeded the byte limit"},"500":{"description":"The function raised"}}}},"/rest/skill/{namespace}/{name}":{"get":{"summary":"One skill guide","description":"`how_it_works` explains what the agent IS and how notes reach it.\n\nAlso answers the HTTP QUERY method, taking the same parameters in an optional JSON body (a body value wins). QUERY is not expressible in OpenAPI 3.1, so it is not listed as an operation.","security":[{"bearerAuth":[]}],"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"},"description":""},{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. how_it_works"}],"responses":{"200":{"description":"One skill guide","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed request, or arguments this function will not take"},"401":{"description":"No usable bearer token"},"403":{"description":"Authenticated, but not entitled to this"},"404":{"description":"No such namespace, function or skill — INCLUDING one hidden from this caller. Gating answers 404 rather than 403, so it cannot confirm that something exists."},"413":{"description":"Response exceeded the byte limit"},"500":{"description":"The function raised"}}}},"/rest/call/{namespace}/{function}":{"post":{"summary":"Call a registered function","description":"The JSON body IS the keyword-argument dict. Which arguments a function takes is NOT described here — ask GET /rest/help/{namespace}/{function}, which answers live and per caller.\n\nThe authenticated user is supplied by the server and must not be sent. `max_bytes_llm` caps the response; it can lower the endpoint's ceiling, never raise it.\n\nPOST only: calling is neither safe nor idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"name":"namespace","in":"path","required":true,"schema":{"type":"string"},"description":""},{"name":"function","in":"path","required":true,"schema":{"type":"string"},"description":""}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Keyword arguments; see the help route for this function."}}}},"responses":{"200":{"description":"The function's result — JSON when it returns JSON, otherwise text.","content":{"application/json":{"schema":{}},"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed request, or arguments this function will not take"},"401":{"description":"No usable bearer token"},"403":{"description":"Authenticated, but not entitled to this"},"404":{"description":"No such namespace, function or skill — INCLUDING one hidden from this caller. Gating answers 404 rather than 403, so it cannot confirm that something exists."},"413":{"description":"Response exceeded the byte limit"},"500":{"description":"The function raised"}}}},"/health":{"get":{"summary":"Liveness, version and database check","description":"No auth. 503 when the database is unreachable.","security":[],"responses":{"200":{"description":"Healthy"},"503":{"description":"Database unreachable"}}}}}}