{
  "openapi": "3.1.0",
  "info": {
    "title": "IXO public website API",
    "version": "1.1.0",
    "description": "The API hosted on ixo.world. Public REST operations include Topic preparation and contact submissions; supported writes declare Idempotency-Key. Auth Hub OAuth protects the separate /v1/mcp Topic preparation resource. Optional services depend on live configuration. Portal handoff remains disabled. The Emerging Platform API on docs.ixo.world is a separate service. Authentication and retries: https://ixo.world/auth.md"
  },
  "servers": [
    {
      "url": "https://ixo.world"
    }
  ],
  "security": [],
  "paths": {
    "/api/topics/config": {
      "get": {
        "operationId": "api_topics_config_get",
        "summary": "Check live Topic capabilities",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/pricing.json": {
      "get": {
        "operationId": "pricing_json_get",
        "summary": "Read published software licence pricing and exclusions",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/topics/prompt": {
      "post": {
        "operationId": "api_topics_prompt_post",
        "summary": "Prepare agent instructions without creating a Topic",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sourceIntent": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4000
                  }
                },
                "required": [
                  "sourceIntent"
                ]
              }
            }
          }
        }
      }
    },
    "/api/topics/recipes": {
      "get": {
        "operationId": "api_topics_recipes_get",
        "summary": "List available Topic recipes",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Returns 503 if the indexer is not configured."
      }
    },
    "/api/topics/validate": {
      "post": {
        "operationId": "api_topics_validate_post",
        "summary": "Validate a proposed Topic composition",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "description": "The composition must satisfy the canonical schema and Portal host constraints linked from /topic-agent.json. This does not persist or publish a Topic.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sourceIntent",
                  "composition"
                ],
                "properties": {
                  "sourceIntent": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4000
                  },
                  "composition": {
                    "$ref": "https://ixo.world/topic-contracts/3.2.0-rc3-website.1/topic-composition.schema.json"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/topics/compose": {
      "post": {
        "operationId": "api_topics_compose_post",
        "summary": "Request a proposed Topic composition",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Requires a configured composer; check composition in /api/topics/config. Does not publish a Topic. Idempotency covers the upstream composition invocation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sourceIntent": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4000
                  }
                },
                "required": [
                  "sourceIntent"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Random UUID per intended operation; reuse with identical content on retries. Confidential, endpoint-scoped. Successful responses replay for 24h (continue: 30min). 409 for changed content or pending/uncertain execution. Do not automatically retry after expiry or with a new key following an uncertain result.",
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9-]{16,100}$"
            }
          }
        ]
      }
    },
    "/api/topics/continue": {
      "post": {
        "operationId": "api_topics_continue_post",
        "summary": "Reserve a temporary Portal continuation",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Disabled until live acceptance tests pass. Check continuation in /api/topics/config; disabled returns 503. This intent-only request reserves a 30-minute reference, not a Portal Topic. Retrying after 30 minutes may create a new reference.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sourceIntent",
                  "kind"
                ],
                "properties": {
                  "sourceIntent": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4000
                  },
                  "kind": {
                    "const": "intent"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Random UUID per intended operation; reuse with identical content on retries. Confidential, endpoint-scoped. Successful responses replay for 24h (continue: 30min). 409 for changed content or pending/uncertain execution. Do not automatically retry after expiry or with a new key following an uncertain result.",
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9-]{16,100}$"
            }
          }
        ]
      }
    },
    "/api/contact": {
      "post": {
        "operationId": "api_contact_post",
        "summary": "Submit a contact enquiry with user consent",
        "security": [],
        "responses": {
          "202": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Request rejected or service unavailable. Inspect error.code and error.message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Sends a message to IXO when intake is configured; otherwise returns 503. Obtain the user's consent before submitting. Public rate limit: 5 requests per minute per client IP. Successful receipt contains accepted, receiptId and requestId.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "intent",
                  "source",
                  "name",
                  "workEmail",
                  "organisation",
                  "consent"
                ],
                "properties": {
                  "intent": {
                    "enum": [
                      "evaluate_platform",
                      "build_platform",
                      "partner_or_invest"
                    ]
                  },
                  "source": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 160
                  },
                  "workEmail": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 254
                  },
                  "organisation": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "productPlatform": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "role": {
                    "type": "string",
                    "maxLength": 160
                  },
                  "message": {
                    "type": "string",
                    "maxLength": 4000
                  },
                  "consent": {
                    "const": true
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Random UUID per intended operation; reuse with identical content on retries. Confidential, endpoint-scoped. Successful responses replay for 24h (continue: 30min). 409 for changed content or pending/uncertain execution. Do not automatically retry after expiry or with a new key following an uncertain result.",
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9-]{16,100}$"
            }
          }
        ]
      }
    },
    "/v1/mcp": {
      "post": {
        "operationId": "website_topic_mcp",
        "summary": "Use authenticated Topic preparation tools",
        "description": "Stateless Streamable HTTP MCP. Supports initialize, tools/list and tools/call. Both tools are read-only and safe to retry; no persistent writes or Portal continuation. Requires topics:prepare from Auth Hub.",
        "security": [
          {
            "authHub": [
              "topics:prepare"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "const": "2.0"
                  },
                  "id": {
                    "type": [
                      "string",
                      "integer"
                    ]
                  },
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result or error"
          },
          "202": {
            "description": "Notification accepted"
          },
          "400": {
            "description": "Invalid protocol request"
          },
          "401": {
            "description": "Missing or invalid Auth Hub token; follow WWW-Authenticate resource_metadata"
          },
          "403": {
            "description": "Insufficient scope or browser origin rejected"
          },
          "404": {
            "description": "Integration disabled"
          },
          "413": {
            "description": "Request body too large"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Service unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "authHub": {
        "type": "oauth2",
        "description": "Auth Hub OAuth 2.1 with PKCE S256 and resource=https://ixo.world/v1/mcp. Tokens must target this resource.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://auth.ixo.earth/oauth/authorize",
            "tokenUrl": "https://auth.ixo.earth/oauth/token",
            "refreshUrl": "https://auth.ixo.earth/oauth/token",
            "scopes": {
              "topics:prepare": "Prepare Topic instructions for review; no publishing, messaging, payments or Portal access."
            }
          }
        }
      }
    }
  }
}
