{
  "openapi": "3.0.3",
  "info": {
    "title": "Xintel Agent API",
    "version": "1.0.0",
    "description": "Xintel builds a forensic, time-series dossier on a public X account from its full public surface — profile and org affiliation, every post (originals, replies, quotes, reposts, long-form notes and Articles), inbound mentions, X's own topic/entity annotations on that content, expanded outbound links, and a network graph derived locally from all of it combined. This API sells the finished result: an **intel report**, a self-contained snapshot an agent can reason over without scraping X, computing metrics, or running its own synthesis pass.\n\nEach report has two layers, both frozen at generation time:\n\n- **Computed facts** — exact, not modeled. Engagement distribution (best/worst posts, percentile thresholds, rate by post type), posting cadence (burst vs steady, hourly/weekday rhythm, longest silences), composition (original/reply/quote/repost mix, media and link rates, language mix), topic and outbound-domain signal, and a derived network of who the account actually engages — mentions, quotes, replies — weighted from the post graph itself, not their follow list.\n- **Grounded interpretation** — an executive summary and strategic assessment, weighted themes with cited evidence, a full voice/register profile (cadence, diction, stance, rhetoric, texture, and the specific devices used) precise enough to draft convincingly in that voice, narrative arcs, audience read, flagged contradictions, and analyst conclusions. The model explains the facts; it does not invent them.\n\nFrom the second report on a handle, a **change layer** is added: measured volume added, metric shifts with percent deltas, topics emerging/fading/sustained, and accounts entering or leaving the network — with its own narrative of what the shift means. Across several reports a handle becomes a real time series, not a snapshot.\n\n**How agents use it:** browse the free shelf for which handles have reports, open a free per-handle menu (ids, dates, models), then buy one or more report bodies at **$0.01 USDC each** on Base via x402. Live unit price is `extensions.unitPriceUsd` on the 402 challenge.\n\nDocs: https://docs.xintel.aispace.bot/agents · Product: https://xintel.aispace.bot",
    "contact": {
      "name": "AiSpace",
      "url": "https://aispace.bot",
      "email": "aispace.dev@proton.me"
    },
    "x-logo": {
      "url": "https://xintel.aispace.bot/aispace-logo-badge.png",
      "altText": "AiSpace",
      "backgroundColor": "#000000"
    },
    "x-guidance": "Browse GET /api/intel/list (free) for handles with published reports. Then GET /api/intel/reports?username=<handle> for a free per-handle menu (report ids, createdAt, model, postCount). To buy report bodies, call the same endpoint with select=all (every report) or select=range (filter by ids and/or from/to) — the first call with no payment returns HTTP 402 with accepts[] and extensions.unitPriceUsd; sign the x402 exact-payment challenge and resend the identical URL with an X-402-Payment header (alias: X-Payment). Price is unitPriceUsd × report count, settled in USDC on Base. Runtime 402 behavior is authoritative over this description."
  },
  "servers": [
    {
      "url": "https://xintel.aispace.bot",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Agent shelf",
      "description": "Browse which X accounts have intel reports, then buy finished analytics + narrative + change-over-time snapshots via x402"
    }
  ],
  "paths": {
    "/api/intel/list": {
      "get": {
        "tags": ["Agent shelf"],
        "operationId": "listSharedReports",
        "summary": "Browse which X accounts have intel reports available",
        "description": "Free shelf index of handles with at least one published report, plus report counts and light profile cues. No auth required. Use this to pick a username before opening its menu or buying.",
        "security": [],
        "responses": {
          "200": {
            "description": "Catalog (configured may be false when KV is not provisioned)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListResponse"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Index read failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/intel/reports": {
      "get": {
        "tags": ["Agent shelf"],
        "operationId": "getSharedReports",
        "summary": "Preview a handle's report menu, or buy its intel report bodies",
        "description": "Without `select`: free menu of available snapshots for a handle (id, createdAt, model, postCount, dateRange) so you can choose what to buy.\n\nWith `select=all` or `select=range`: returns full intel report bodies after x402 payment at $0.01 USDC × N on Base. No payment header → 402 with `accepts[]` / `extensions`; retry the same URL with `X-402-Payment` (or `X-Payment`).\n\nEach body is a frozen dossier — computed engagement/cadence/composition/network facts, an evidence-grounded narrative (themes, voice/register, audience read, contradictions, conclusions), and, past the first report, a measured change summary versus the prior snapshot. Ready for agent reasoning as-is; nothing to re-derive.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.01"
          },
          "protocols": [{ "x402": {} }]
        },
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "description": "X handle (with or without leading @)",
            "schema": {
              "type": "string",
              "example": "AskVenice"
            }
          },
          {
            "name": "select",
            "in": "query",
            "required": false,
            "description": "Omit for free menu. `all` = every report body. `range` = filter by ids and/or createdAt window.",
            "schema": {
              "type": "string",
              "enum": ["all", "range"],
              "example": "all"
            }
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Comma-separated report ids (for select=range)",
            "schema": {
              "type": "string",
              "example": "id1,id2"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Inclusive lower bound on report createdAt (ISO-8601; for select=range)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Inclusive upper bound on report createdAt (ISO-8601; for select=range)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "X-402-Payment",
            "in": "header",
            "required": false,
            "description": "x402 payment payload from the prior 402 challenge. Alias: X-Payment.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Free menu (no select) or paid report bodies (with select + settled payment)",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ReportMenuResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ReportBodiesResponse"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad query (missing username, invalid select, empty range filters)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required — read accepts[0] and extensions, sign, retry with X-402-Payment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            }
          },
          "404": {
            "description": "Unknown username or no matching reports",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Payment id already used",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Settlement not configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Upstream / storage failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Intel KV not configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Agent shelf"],
        "operationId": "buySharedReports",
        "summary": "Buy a handle's intel report bodies (JSON body variant of GET)",
        "description": "Same resource as `GET /api/intel/reports`, taking its inputs as a JSON body instead of query params — convenient for agents that prefer POST. Send `{ \"username\": \"<handle>\", \"select\": \"all\" }` (or `select=range` with `ids` and/or `from`/`to`). With no payment header the response is HTTP 402 with `accepts[]` (also base64 in the `Payment-Required` header) and `extensions.unitPriceUsd`; sign the x402 exact-payment challenge and resend the identical request with an `X-402-Payment` (alias `X-Payment`) header. Price is $0.01 USDC × report count, settled on Base. Omit `select` to receive the free per-handle menu. Runtime 402 behavior is authoritative.",
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "0.01"
          },
          "protocols": [{ "x402": {} }]
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReportsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Free menu (no select) or paid report bodies (with select + settled payment)",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ReportMenuResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ReportBodiesResponse"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad input (missing username, invalid select, empty range filters)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required — read accepts[0] and extensions, sign, retry with X-402-Payment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            }
          },
          "404": {
            "description": "Unknown username or no matching reports",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Payment id already used",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Settlement not configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Upstream / storage failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Intel KV not configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ReportsRequest": {
        "type": "object",
        "description": "Inputs for POST /api/intel/reports (JSON body variant of the GET query params).",
        "required": ["username"],
        "properties": {
          "username": {
            "type": "string",
            "description": "X handle (with or without leading @)",
            "example": "AskVenice"
          },
          "select": {
            "type": "string",
            "enum": ["all", "range"],
            "description": "Omit for the free menu. `all` = every report body. `range` = filter by ids and/or createdAt window.",
            "example": "all"
          },
          "ids": {
            "type": "string",
            "description": "Comma-separated report ids (for select=range)",
            "example": "id1,id2"
          },
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "Inclusive lower bound on report createdAt (ISO-8601; for select=range)"
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "Inclusive upper bound on report createdAt (ISO-8601; for select=range)"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "requiredUsd": {
            "type": "number"
          },
          "paidUsd": {
            "type": "number"
          }
        },
        "additionalProperties": true
      },
      "SharedIndexEntry": {
        "type": "object",
        "required": [
          "username",
          "displayName",
          "avatarUrl",
          "followers",
          "postCount",
          "reportCount",
          "gatheredAt"
        ],
        "properties": {
          "username": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "avatarUrl": {
            "type": "string"
          },
          "followers": {
            "type": "integer"
          },
          "postCount": {
            "type": "integer"
          },
          "reportCount": {
            "type": "integer"
          },
          "gatheredAt": {
            "type": "string",
            "format": "date-time"
          },
          "affiliationBadgeUrl": {
            "type": "string",
            "nullable": true
          },
          "affiliationLabel": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ListResponse": {
        "type": "object",
        "required": ["configured", "entries"],
        "properties": {
          "configured": {
            "type": "boolean"
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SharedIndexEntry"
            }
          }
        }
      },
      "ReportMenuItem": {
        "type": "object",
        "required": ["id", "createdAt", "model", "postCount", "dateRange"],
        "properties": {
          "id": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "model": {
            "type": "string"
          },
          "postCount": {
            "type": "integer"
          },
          "dateRange": {
            "type": "object",
            "nullable": true,
            "properties": {
              "from": {
                "type": "string"
              },
              "to": {
                "type": "string"
              }
            }
          }
        }
      },
      "ReportMenuResponse": {
        "type": "object",
        "required": ["username", "reportCount", "reports"],
        "properties": {
          "username": {
            "type": "string"
          },
          "reportCount": {
            "type": "integer"
          },
          "reports": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReportMenuItem"
            }
          }
        }
      },
      "IntelReportSnapshot": {
        "type": "object",
        "description": "A frozen, self-contained intel dossier on one X handle at one point in time: exact computed facts (engagement, cadence, composition, topics, derived network), an evidence-grounded AI narrative (summary, strategic assessment, themes, voice/register, contradictions, conclusions), and — past the first report on that handle — a measured change summary versus the prior snapshot. Treat unknown fields as forward-compatible.",
        "required": [
          "id",
          "createdAt",
          "model",
          "synthesisSettings",
          "meta",
          "analytics",
          "narrative",
          "changeSummary",
          "previousReportId"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "model": {
            "type": "string"
          },
          "synthesisSettings": {
            "type": "object",
            "additionalProperties": true
          },
          "meta": {
            "type": "object",
            "additionalProperties": true
          },
          "analytics": {
            "type": "object",
            "additionalProperties": true
          },
          "narrative": {
            "type": "object",
            "additionalProperties": true
          },
          "changeSummary": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "previousReportId": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": true
      },
      "ReportBodiesResponse": {
        "type": "object",
        "required": ["username", "select", "reportCount", "reports"],
        "properties": {
          "username": {
            "type": "string"
          },
          "select": {
            "type": "string",
            "enum": ["all", "range"]
          },
          "reportCount": {
            "type": "integer"
          },
          "chargedUsd": {
            "type": "number",
            "description": "Required charge (unit × N); present on paid responses"
          },
          "reports": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IntelReportSnapshot"
            }
          }
        }
      },
      "PaymentAccept": {
        "type": "object",
        "required": ["protocol", "version", "network", "asset", "amount", "payTo"],
        "properties": {
          "protocol": {
            "type": "string",
            "example": "x402"
          },
          "version": {
            "type": "integer",
            "example": 2
          },
          "network": {
            "type": "string",
            "example": "eip155:8453"
          },
          "asset": {
            "type": "string",
            "description": "USDC contract on Base",
            "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
          },
          "amount": {
            "type": "string",
            "description": "USDC base units (6 decimals). 10000 = $0.01"
          },
          "payTo": {
            "type": "string",
            "description": "Receiver wallet for this deployment"
          }
        }
      },
      "PaymentRequired": {
        "type": "object",
        "required": ["x402Version", "error", "accepts", "extensions"],
        "properties": {
          "x402Version": {
            "type": "integer",
            "example": 2
          },
          "error": {
            "type": "string",
            "example": "Payment required"
          },
          "accepts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentAccept"
            }
          },
          "extensions": {
            "type": "object",
            "properties": {
              "chainId": {
                "type": "integer",
                "example": 8453
              },
              "tokenDecimals": {
                "type": "integer",
                "example": 6
              },
              "unitPriceUsd": {
                "type": "number",
                "example": 0.01
              },
              "reportCount": {
                "type": "integer"
              },
              "select": {
                "type": "string"
              },
              "resource": {
                "type": "string"
              }
            },
            "additionalProperties": true
          }
        }
      }
    }
  }
}