openapi: 3.1.0
info:
  title: Thyris GEO API
  version: 2026-09-20
  description: Workspace-scoped APIs for Generative Engine Optimization measurement, target graphs, tracking, reports, and governed automation.
servers:
  - url: https://geo.thyris.cloud
security:
  - bearerAuth: []
paths:
  /api/v1/geo/analytics:
    get:
      summary: Query versioned GEO datasets
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: dataset
          in: query
          required: true
          schema:
            {
              type: string,
              enum:
                [
                  metrics,
                  recommendations,
                  actions,
                  alerts,
                  reports,
                  attribution,
                  campaigns,
                  targets,
                  content,
                  artifacts,
                  publications,
                  tracking_events,
                  experiments,
                  dashboards,
                  saved_views,
                ],
            }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 500, default: 100 }
      responses:
        "200": { description: Dataset page }
  /api/v1/geo/target-graph:
    get:
      summary: Read targets, relations, and optional immutable history
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: projectId
          in: query
          schema: { type: string, format: uuid }
        - name: includeHistory
          in: query
          schema: { type: boolean, default: false }
      responses: { "200": { description: Target Graph } }
    post:
      summary: Import a graph or merge canonical targets
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string }
      responses:
        {
          "200": { description: Mutation receipt },
          "409": { description: Idempotency conflict },
          "422": { description: Invalid or cyclic graph },
        }
  /api/v1/geo/privacy:
    get:
      summary: Read privacy request status
      parameters: [{ $ref: "#/components/parameters/WorkspaceId" }]
      responses:
        { "200": { description: Requests with redacted subject hashes } }
    post:
      summary: Submit pseudonymous access or deletion request
      responses: { "202": { description: Accepted } }
  /api/v1/geo/mcp:
    post:
      summary: MCP JSON-RPC endpoint with read tools and approval-request tool
      responses: { "200": { description: JSON-RPC response } }
  /api/v1/geo/exports/{exportId}:
    get:
      summary: Download JSON, CSV, NDJSON, XLSX, or PDF export
      parameters:
        - name: exportId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        {
          "200": { description: Export payload },
          "403": { description: Expired or unauthorized },
        }
  /api/v2/geo/events:
    post:
      summary: Ingest consent-aware pseudonymous GEO tracking events
      security: []
      responses:
        {
          "202": { description: Event batch accepted },
          "401": { description: Invalid site token },
        }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
  parameters:
    WorkspaceId:
      name: workspaceId
      in: query
      required: true
      schema: { type: string, format: uuid }