{
  "openapi": "3.1.0",
  "info": {
    "title": "Weftd API",
    "description": "Weftd helps businesses make their knowledge, services and expertise accessible to AI. We provide the tools to create, connect and manage AI Presences, so anyone can interact with your business, through any AI, at any time.\n\nThis API lets an agent ask a natural-language question about \"Weftd\" and get the answer.\n\nWith mode=context (default) it returns an AI-written answer and the sources used. With mode=search it returns only the entries ranked by relevance, without AI. type=json gives a structured response, type=txt plain text.\n\nThis space's MCP server is available at https://weftd.weftd.space/mcp.\n\nVersioning: the major version is in the path (/api/v1(/api/v2(RFC 8594) giving its retirement date, at least 6 months ahead, plus a `Link: <...>; rel=\"successor-version\"` to its replacement. Rate limits: every response carries `RateLimit-Policy` and `RateLimit` (IETF httpapi ratelimit headers) so a client can slow down before a 429; a 429 also carries `Retry-After`.",
    "version": "1.0.0"
  },
  "x-api-lifecycle": {
    "currentVersion": "v1",
    "versioning": "path",
    "versionedPath": "/api/v1",
    "unversionedAlias": "/api",
    "deprecationSignals": [
      "Deprecation (RFC 9745)",
      "Sunset (RFC 8594)",
      "Link rel=\"successor-version\""
    ],
    "minimumNoticeMonths": 6
  },
  "servers": [
    {
      "url": "https://weftd.weftd.space"
    }
  ],
  "externalDocs": {
    "description": "Agent-oriented documentation (llms.txt)",
    "url": "https://weftd.weftd.space/llms.txt"
  },
  "tags": [
    {
      "name": "Query",
      "description": "Query the space's knowledge."
    }
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "operationId": "querySpace",
        "summary": "Ask the space a question",
        "description": "Ask a natural-language question about this space's content. Use mode=search to get only the relevant entries.",
        "tags": [
          "Query"
        ],
        "security": [
          {},
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "The question, in natural language.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "search",
                "context"
              ],
              "default": "context",
              "description": "context: AI-written answer with its sources. search: entries ranked by relevance, no AI."
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "txt",
                "json"
              ],
              "default": "txt",
              "description": "Response format: plain text (txt) or structured JSON (json)."
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 4,
              "description": "Maximum number of knowledge entries used or returned."
            }
          }
        ],
        "responses": {
          "200": {
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "description": "Answer to the question. With mode=context: an AI-written answer and its sources. With mode=search: ranked entries, no AI. With type=txt, the same content as plain text.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/QueryResponse"
                    },
                    {
                      "$ref": "#/components/schemas/QuerySearchResponse"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request: missing query, unreadable JSON, or limit outside 1-50.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Access denied: API key missing, invalid, or not allowed for this space.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Space not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The space is not deployed (code NOT_DEPLOYED).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached, or the space has insufficient credits (code INSUFFICIENT_CREDITS). Honor Retry-After when present.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "querySpaceWithBody",
        "summary": "Ask the space a question (JSON body)",
        "description": "Ask a natural-language question about this space's content. Use mode=search to get only the relevant entries.",
        "tags": [
          "Query"
        ],
        "security": [
          {},
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "description": "Answer to the question. With mode=context: an AI-written answer and its sources. With mode=search: ranked entries, no AI. With type=txt, the same content as plain text.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/QueryResponse"
                    },
                    {
                      "$ref": "#/components/schemas/QuerySearchResponse"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request: missing query, unreadable JSON, or limit outside 1-50.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Access denied: API key missing, invalid, or not allowed for this space.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Space not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The space is not deployed (code NOT_DEPLOYED).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached, or the space has insufficient credits (code INSUFFICIENT_CREDITS). Honor Retry-After when present.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api": {
      "get": {
        "operationId": "querySpaceUnversioned",
        "summary": "Ask the space a question",
        "description": "Ask a natural-language question about this space's content. Use mode=search to get only the relevant entries.",
        "tags": [
          "Query"
        ],
        "security": [
          {},
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "The question, in natural language.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "search",
                "context"
              ],
              "default": "context",
              "description": "context: AI-written answer with its sources. search: entries ranked by relevance, no AI."
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "txt",
                "json"
              ],
              "default": "txt",
              "description": "Response format: plain text (txt) or structured JSON (json)."
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 4,
              "description": "Maximum number of knowledge entries used or returned."
            }
          }
        ],
        "responses": {
          "200": {
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "description": "Answer to the question. With mode=context: an AI-written answer and its sources. With mode=search: ranked entries, no AI. With type=txt, the same content as plain text.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/QueryResponse"
                    },
                    {
                      "$ref": "#/components/schemas/QuerySearchResponse"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request: missing query, unreadable JSON, or limit outside 1-50.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Access denied: API key missing, invalid, or not allowed for this space.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Space not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The space is not deployed (code NOT_DEPLOYED).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached, or the space has insufficient credits (code INSUFFICIENT_CREDITS). Honor Retry-After when present.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "querySpaceWithBodyUnversioned",
        "summary": "Ask the space a question (JSON body)",
        "description": "Ask a natural-language question about this space's content. Use mode=search to get only the relevant entries.",
        "tags": [
          "Query"
        ],
        "security": [
          {},
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "description": "Answer to the question. With mode=context: an AI-written answer and its sources. With mode=search: ranked entries, no AI. With type=txt, the same content as plain text.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/QueryResponse"
                    },
                    {
                      "$ref": "#/components/schemas/QuerySearchResponse"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request: missing query, unreadable JSON, or limit outside 1-50.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Access denied: API key missing, invalid, or not allowed for this space.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Space not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The space is not deployed (code NOT_DEPLOYED).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached, or the space has insufficient credits (code INSUFFICIENT_CREDITS). Honor Retry-After when present.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimit": {
        "description": "Current state, e.g. `\"default\";r=59;t=42`: r requests left, t seconds until the window resets.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimitPolicy": {
        "description": "The policy, e.g. `\"default\";q=60;w=3600`: q requests per window of w seconds.",
        "schema": {
          "type": "string"
        }
      },
      "Deprecation": {
        "description": "Present only on a deprecated version (RFC 9745): when it was deprecated, as @<unix-seconds>.",
        "schema": {
          "type": "string"
        }
      },
      "Sunset": {
        "description": "Present only on a deprecated version (RFC 8594): the HTTP date it stops answering, at least 6 months ahead.",
        "schema": {
          "type": "string"
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key created in the space's Developer API settings."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key created in the space's Developer API settings."
      }
    },
    "schemas": {
      "QueryRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "description": "The question, in natural language."
          },
          "mode": {
            "type": "string",
            "enum": [
              "search",
              "context"
            ],
            "default": "context",
            "description": "context: AI-written answer with its sources. search: entries ranked by relevance, no AI."
          },
          "type": {
            "type": "string",
            "enum": [
              "txt",
              "json"
            ],
            "default": "txt",
            "description": "Response format: plain text (txt) or structured JSON (json)."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 4,
            "description": "Maximum number of knowledge entries used or returned."
          },
          "image": {
            "type": "string",
            "description": "Optional image: base64 or URL."
          }
        }
      },
      "QuerySource": {
        "type": "object",
        "required": [
          "id",
          "title"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "snippet": {
            "type": "string"
          },
          "relevance": {
            "type": "number"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "QueryResponse": {
        "type": "object",
        "required": [
          "answer",
          "sources"
        ],
        "properties": {
          "answer": {
            "type": "string",
            "description": "AI-written answer."
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuerySource"
            }
          },
          "usage": {
            "type": "object",
            "required": [
              "tokensUsed",
              "model"
            ],
            "properties": {
              "tokensUsed": {
                "type": "integer"
              },
              "model": {
                "type": "string"
              }
            }
          }
        }
      },
      "QuerySearchResponse": {
        "type": "object",
        "required": [
          "results",
          "total",
          "query"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuerySource"
            }
          },
          "total": {
            "type": "integer"
          },
          "query": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "E.g. NOT_DEPLOYED or INSUFFICIENT_CREDITS."
          },
          "message": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "fallback": {
            "type": "string",
            "description": "Fallback text (space contact) when credits are missing."
          }
        }
      }
    }
  }
}