{
  "openapi": "3.1.1",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "Aprixity Public Content API",
    "version": "1.0.0",
    "summary": "Read-only access to published Aprixity knowledge content.",
    "description": "The public API exposes published article metadata, article details, and answer-first article representations. It does not expose content mutations, lead data, or operational endpoints."
  },
  "servers": [
    {
      "url": "https://aprixity.run"
    }
  ],
  "externalDocs": {
    "description": "Aprixity Developer Resources",
    "url": "https://aprixity.run/en/developers"
  },
  "security": [],
  "tags": [
    {
      "name": "Knowledge",
      "description": "Published Aprixity knowledge content."
    },
    {
      "name": "Answer-first content",
      "description": "Compact representations for retrieval and answer systems."
    }
  ],
  "paths": {
    "/api/knowledge/articles": {
      "get": {
        "operationId": "listPublishedArticles",
        "summary": "List published articles",
        "description": "Returns native Aprixity articles that are published. Optional filters narrow the result set. German and English translations are included when available; syndicated records are excluded.",
        "tags": ["Knowledge"],
        "parameters": [
          {
            "name": "contentType",
            "in": "query",
            "required": false,
            "description": "Filter by the stored article content type.",
            "schema": {
              "type": "string",
              "enum": ["framework", "guide", "research", "medium"]
            }
          },
          {
            "name": "locale",
            "in": "query",
            "required": false,
            "description": "Filter the translations returned for each article to this locale. Articles remain in the response when no translation matches, with an empty translations array.",
            "schema": {
              "$ref": "#/components/schemas/Locale"
            }
          },
          {
            "name": "awarenessLevel",
            "in": "query",
            "required": false,
            "description": "Filter by the stored audience-awareness classification.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published article list.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Article"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/knowledge/articles/{slug}": {
      "get": {
        "operationId": "getPublishedArticle",
        "summary": "Get one published article",
        "description": "Returns one native Aprixity article with every available translation and optional framework metadata. This operation does not accept a locale filter; syndicated records are excluded.",
        "tags": ["Knowledge"],
        "parameters": [
          {
            "$ref": "#/components/parameters/ArticleSlug"
          }
        ],
        "responses": {
          "200": {
            "description": "Published article with translations.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleDetail"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/aeo/articles/{slug}": {
      "get": {
        "operationId": "getAnswerFirstArticle",
        "summary": "Get an answer-first article representation",
        "description": "Returns a compact localized representation of one native Aprixity article. The locale defaults to English; syndicated records are excluded.",
        "tags": ["Answer-first content"],
        "parameters": [
          {
            "$ref": "#/components/parameters/ArticleSlug"
          },
          {
            "name": "locale",
            "in": "query",
            "required": false,
            "description": "Requested translation locale. Defaults to `en`.",
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Locale"
                }
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Localized answer-first article representation.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnswerFirstArticle"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "CacheControl": {
        "description": "Public cache policy for the representation.",
        "schema": {
          "type": "string"
        }
      }
    },
    "parameters": {
      "ArticleSlug": {
        "name": "slug",
        "in": "path",
        "required": true,
        "description": "Article slug obtained from the published article list.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$"
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "The article or requested translation does not exist.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "RateLimited": {
        "description": "The public API request limit has been reached.",
        "headers": {
          "RateLimit-Policy": {
            "description": "Applied request quota policy.",
            "schema": {
              "type": "string"
            }
          },
          "RateLimit-Limit": {
            "description": "Maximum requests permitted in the current quota window.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          "RateLimit-Remaining": {
            "description": "Requests remaining in the current quota window.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          "RateLimit-Reset": {
            "description": "Seconds until the current quota resets.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "InternalError": {
        "description": "The API could not complete the request.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    },
    "schemas": {
      "Locale": {
        "type": "string",
        "enum": ["de", "en"]
      },
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 9457 problem details with stable Aprixity recovery extensions.",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "message",
          "resolution"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string",
            "description": "Request path without query parameters."
          },
          "code": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]+$"
          },
          "message": {
            "type": "string",
            "description": "Compatibility alias of `detail`."
          },
          "resolution": {
            "type": "string"
          },
          "error": {
            "type": "string",
            "description": "Optional compatibility member retained by an existing endpoint."
          }
        },
        "additionalProperties": true
      },
      "Article": {
        "type": "object",
        "required": ["id", "slug", "contentType"],
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "contentType": {
            "type": "string"
          },
          "primaryQuestion": {
            "type": ["string", "null"]
          },
          "shortAnswer": {
            "type": ["string", "null"]
          },
          "keyTakeaways": {
            "type": ["array", "null"],
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "difficulty": {
            "type": ["string", "null"]
          },
          "estimatedReadTime": {
            "type": ["integer", "null"]
          },
          "firstPublished": {
            "type": "string",
            "format": "date-time"
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time"
          },
          "isPublished": {
            "type": ["boolean", "null"]
          },
          "translations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ArticleTranslation"
            }
          }
        },
        "additionalProperties": true
      },
      "ArticleTranslation": {
        "type": "object",
        "required": ["id", "articleId", "locale", "title", "content"],
        "properties": {
          "id": {
            "type": "string"
          },
          "articleId": {
            "type": "string"
          },
          "locale": {
            "$ref": "#/components/schemas/Locale"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": ["string", "null"]
          },
          "content": {
            "type": "string"
          },
          "detailedAnswer": {
            "type": ["string", "null"]
          },
          "faqPairs": {
            "type": ["array", "null"],
            "items": {
              "$ref": "#/components/schemas/FaqPair"
            }
          },
          "citations": {
            "type": ["array", "null"],
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      },
      "ArticleDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Article"
          },
          {
            "type": "object",
            "required": ["translations"],
            "properties": {
              "translations": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ArticleTranslation"
                }
              },
              "framework": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Framework"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        ]
      },
      "Framework": {
        "type": "object",
        "properties": {
          "name": {
            "type": ["string", "null"]
          },
          "acronym": {
            "type": ["string", "null"]
          },
          "useCases": {
            "type": ["array", "null"],
            "items": {
              "type": "string"
            }
          },
          "prerequisites": {
            "type": ["array", "null"],
            "items": {
              "type": "string"
            }
          },
          "tools": {
            "type": ["array", "null"],
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "timeToImplement": {
            "type": ["string", "null"]
          }
        },
        "additionalProperties": true
      },
      "FaqPair": {
        "type": "object",
        "required": ["question", "answer"],
        "properties": {
          "question": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "AnswerFirstArticle": {
        "type": "object",
        "required": [
          "question",
          "shortAnswer",
          "detailedAnswer",
          "keyTakeaways",
          "faq",
          "meta",
          "citations",
          "canonicalUrl"
        ],
        "properties": {
          "question": {
            "type": ["string", "null"]
          },
          "shortAnswer": {
            "type": ["string", "null"]
          },
          "detailedAnswer": {
            "type": ["string", "null"]
          },
          "keyTakeaways": {
            "type": ["array", "null"],
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "faq": {
            "type": ["array", "null"],
            "items": {
              "$ref": "#/components/schemas/FaqPair"
            }
          },
          "framework": {
            "$ref": "#/components/schemas/Framework"
          },
          "meta": {
            "type": "object",
            "required": ["contentType", "language"],
            "properties": {
              "contentType": {
                "type": "string"
              },
              "difficulty": {
                "type": ["string", "null"]
              },
              "estimatedReadTime": {
                "type": ["integer", "null"]
              },
              "published": {
                "type": "string",
                "format": "date-time"
              },
              "updated": {
                "type": "string",
                "format": "date-time"
              },
              "language": {
                "$ref": "#/components/schemas/Locale"
              },
              "isCustomerResource": {
                "type": ["boolean", "null"]
              }
            },
            "additionalProperties": false
          },
          "citations": {
            "type": ["array", "null"],
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "canonicalUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "additionalProperties": false
      }
    }
  }
}