{
  "openapi": "3.1.0",
  "info": {
    "title": "Palace Beacon developer preview",
    "version": "1.1.0",
    "description": "Website context and local agent gateway. No public hosted agent service is provisioned."
  },
  "paths": {
    "/api/context": {
      "get": {
        "summary": "Available request observations; enrichment is optional",
        "responses": {
          "200": {
            "description": "Context version 1; unavailable evidence stays explicit",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "schemaVersion",
                    "observedAt",
                    "observations",
                    "enrichment"
                  ],
                  "properties": {
                    "schemaVersion": {
                      "const": 1
                    },
                    "observedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "observations": {
                      "type": "object",
                      "additionalProperties": {
                        "$ref": "./observation.schema.json"
                      },
                      "properties": {
                        "campusLocation": {
                          "allOf": [
                            {
                              "$ref": "./observation.schema.json"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "value": {
                                  "anyOf": [
                                    {
                                      "$ref": "./location.schema.json#/$defs/CampusLocation"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              }
                            }
                          ]
                        },
                        "officeAreas": {
                          "allOf": [
                            {
                              "$ref": "./observation.schema.json"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "value": {
                                  "anyOf": [
                                    {
                                      "$ref": "./location.schema.json#/$defs/OfficeAreaResult"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              }
                            }
                          ]
                        }
                      }
                    },
                    "enrichment": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://palacebeacon.com",
            "description": "Website origin; independent of local agent gateway"
          }
        ],
        "parameters": [
          {
            "name": "enrich",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ]
      }
    },
    "/v1/taxonomy": {
      "get": {
        "summary": "Find up to 20 eligible categories",
        "servers": [
          {
            "url": "http://127.0.0.1:8958",
            "description": "Local gateway; not a public service"
          }
        ],
        "security": [
          {
            "appKey": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "topics"
                  ],
                  "properties": {
                    "topics": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, schema, grant or domain request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid server app key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Route not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "POST requires application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Local gateway capacity reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events": {
      "post": {
        "summary": "Admit structured interest evidence",
        "servers": [
          {
            "url": "http://127.0.0.1:8958",
            "description": "Local gateway; not a public service"
          }
        ],
        "security": [
          {
            "appKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "./interests.schema.json#/$defs/AgentInterestEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "eventId",
                    "duplicate"
                  ],
                  "properties": {
                    "eventId": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200
                    },
                    "duplicate": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, schema, grant or domain request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid server app key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Route not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "POST requires application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Local gateway capacity reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/profile": {
      "get": {
        "summary": "Read a purpose-scoped interest profile",
        "servers": [
          {
            "url": "http://127.0.0.1:8958",
            "description": "Local gateway; not a public service"
          }
        ],
        "security": [
          {
            "appKey": []
          }
        ],
        "parameters": [
          {
            "name": "subject",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "name": "purpose",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "ads",
                "personalization"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "./interests.schema.json#/$defs/AgentProfile"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, schema, grant or domain request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid server app key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Route not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "POST requires application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Local gateway capacity reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/retract": {
      "post": {
        "summary": "Retract an event and retain its replay tombstone",
        "servers": [
          {
            "url": "http://127.0.0.1:8958",
            "description": "Local gateway; not a public service"
          }
        ],
        "security": [
          {
            "appKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "subject",
                  "eventId"
                ],
                "properties": {
                  "subject": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "eventId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "retracted"
                  ],
                  "properties": {
                    "retracted": {
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, schema, grant or domain request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid server app key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Route not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "POST requires application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Local gateway capacity reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/revoke": {
      "post": {
        "summary": "Revoke a grant and erase its source events",
        "servers": [
          {
            "url": "http://127.0.0.1:8958",
            "description": "Local gateway; not a public service"
          }
        ],
        "security": [
          {
            "appKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "subject",
                  "grantId"
                ],
                "properties": {
                  "subject": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "grantId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "revoked"
                  ],
                  "properties": {
                    "revoked": {
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON, schema, grant or domain request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid server app key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Route not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "POST requires application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Local gateway capacity reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "appKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Server-only key provisioned to an agent-enabled app."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}