openapi: "3.1.0"
info:
  title: ar-agents public API
  summary: Public endpoints for the AR sociedad-IA reference implementation: discovery, demo agent, audit-log read + verify + export + stream, badge, auto-incorporate wizard.
  description: "The endpoints below are all unauthenticated + idempotent in their default verbs (GET). POST endpoints are explicitly marked; some are rate-limited. The audit-log endpoints implement RFC-004 v1; the discovery endpoint implements RFC-002 v1; the auto-incorporate endpoint implements the wizard backing RFC-001 § 6.\n\nMachine-readable schema. Source: https://ar-agents.vercel.app/api/openapi"
  version: "1.0.0"
  contact:
    name: Nazareno Clemente
    email: "naza@helloastro.co"
    url: https://ar-agents.vercel.app
  license:
    name: MIT (code) + CC-BY-4.0 (specs)
    url: https://github.com/ar-agents/ar-agents/blob/main/LICENSE
servers:
  - url: https://ar-agents.vercel.app
    description: Production
externalDocs:
  description: Architecture + RFCs
  url: https://ar-agents.vercel.app/rfcs/004
tags:
  - name: audit
    description: RFC-004 operational-log endpoints
  - name: discovery
    description: RFC-002 well-known discovery
  - name: incorporate
    description: Sociedad-IA wizard
  - name: demo
    description: Reference agent + tamper demo
  - name: badge
    description: SVG verification badge
paths:
  "/api/play/audit/{sessionId}":
    get:
      operationId: readAuditSession
      summary: Read full audit timeline for a session
      description: "Returns the entries array for the given sessionId. Set `?verify=1` to include `total/verified/tampered/hmacWired` counts. Public; no auth."
      tags:
        - audit
      parameters:
        - name: sessionId
          in: path
          required: true
          description: "Session id (8–64 chars, [A-Za-z0-9_-])."
          schema:
            type: string
            pattern: "^[A-Za-z0-9_-]{8,64}$"
        - name: verify
          in: query
          required: false
          description: "If `1`, include HMAC verification counts."
          schema:
            type: string
            enum:
              - "1"
      responses:
        "200":
          description: OK
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/AuditPayload"
        "400":
          description: Invalid sessionId format
  "/api/play/audit/{sessionId}/csv":
    get:
      operationId: exportAuditSessionCsv
      summary: Export audit timeline as RFC-4180 CSV with UTF-8 BOM
      description: Returns the entries for the given sessionId as CSV. Headers: ts, tool, governance, durationMs, errored, hmac, input, output. Designed for Excel/Sheets ingest by regulatory tooling.
      tags:
        - audit
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            pattern: "^[A-Za-z0-9_-]{8,64}$"
      responses:
        "200":
          description: CSV file
          content:
            "text/csv":
              schema:
                type: string
  "/api/play/audit-stream/{sessionId}":
    get:
      operationId: streamAuditSession
      summary: Server-Sent Events stream of new audit entries
      description: "Returns `text/event-stream` with one `event: append` per new entry + `event: keepalive` every 30s. Use EventSource on the client to subscribe. Optional v1, recommended v1.1+ per RFC-004 § 5."
      tags:
        - audit
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            pattern: "^[A-Za-z0-9_-]{8,64}$"
      responses:
        "200":
          description: Event stream
          content:
            "text/event-stream":
              schema:
                type: string
  "/api/badge/{sessionId}":
    get:
      operationId: verificationBadge
      summary: Get an SVG verification badge for a session
      description: "Returns a shields.io-style SVG showing the session's verify status. Suitable for embedding in READMEs, PRs, etc. ETag + Cache-Control set."
      tags:
        - badge
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            pattern: "^[A-Za-z0-9_-]{8,64}$"
      responses:
        "200":
          description: SVG badge
          content:
            "image/svg+xml":
              schema:
                type: string
  "/api/discovery":
    get:
      operationId: discovery
      summary: RFC-002 agent-discovery manifest
      description: "Returns the discovery manifest (well-known agents.json shape) advertising this site's capabilities + audit endpoints + RFC conformance."
      tags:
        - discovery
      responses:
        "200":
          description: OK
          content:
            "application/json":
              schema:
                type: object
  "/api/auto-incorporate":
    post:
      operationId: autoIncorporate
      summary: Generate a sociedad-IA from form input
      description: Takes a description of a sociedad (denominacion, capital, objeto, representante) and returns a generated source-file pack + audit-log session id. Used by the /incorporar wizard. Rate-limited.
      tags:
        - incorporate
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/IncorporateInput"
      responses:
        "200":
          description: Generation result
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/IncorporateResult"
        "400":
          description: Validation error
        "429":
          description: Rate limited
  "/api/play":
    post:
      operationId: runReferenceAgent
      summary: Run the reference agent against an input
      description: Executes the demo agent (Vercel AI SDK 6 Experimental_Agent) over the provided prompt + creates an audit-log session. Returns the sessionId + assistant response.
      tags:
        - demo
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              type: object
              properties:
                prompt:
                  type: string
                sessionId:
                  type: string
                  pattern: "^[A-Za-z0-9_-]{8,64}$"
              required:
                - prompt
      responses:
        "200":
          description: Agent run completed
          content:
            "application/json":
              schema:
                type: object
  "/api/play/tamper-demo":
    post:
      operationId: tamperDemo
      summary: Inject a deliberately-tampered entry for verification demo
      description: "Appends an entry whose HMAC does NOT match its canonical form, so the /verify page surfaces a tampered count > 0. Test-only; rate-limited."
      tags:
        - demo
      responses:
        "200":
          description: OK
  "/api/audit-summary/{sessionId}":
    get:
      operationId: auditSummary
      summary: Aggregated stats for a session (governance, latency quantiles, anomalies)
      description: Lightweight live computation of recipe-25 aggregates over a single session: governance breakdown, tool usage, latency quantiles per-tool, anomaly flags (clock-skew, governance-shift, llm-error-without-fallback, missing-hmac), HMAC verification counts.
      tags:
        - audit
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            pattern: "^[A-Za-z0-9_-]{8,64}$"
      responses:
        "200":
          description: Summary JSON
          content:
            "application/json":
              schema:
                type: object
  "/api/cert-badge":
    get:
      operationId: certBadge
      summary: Live shields.io-style SVG badge with RFC-002+004 score for any URL
      description: Returns an embeddable SVG badge showing the live conformance score + rating for the target URL. Calls /api/certifier under the hood. Cached 60s.
      tags:
        - badge
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            format: uri
        - name: sessionId
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: SVG
          content:
            "image/svg+xml":
              schema:
                type: string
  "/api/openapi.yaml":
    get:
      operationId: openApiYaml
      summary: YAML mirror of the OpenAPI 3.1 schema
      description: Same content as /api/openapi but serialized as YAML. For codegen / Swagger UI / Postman.
      tags:
        - discovery
      responses:
        "200":
          description: YAML
          content:
            "application/yaml":
              schema:
                type: string
  "/api/certifier":
    get:
      operationId: certifyUrl
      summary: Score a URL 0-100 against RFC-002 + RFC-004 + RFC-005 (~11 checks)
      description: "Runs HTTP fetches against the target's /.well-known/agents.json, audit endpoints, OpenAPI, etc. Honors rfcConformance claims (skip vs fail). Returns a Certification JSON with per-check breakdown."
      tags:
        - discovery
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            format: uri
        - name: sessionId
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Certification JSON
          content:
            "application/json":
              schema:
                type: object
  "/api/conformance-history":
    get:
      operationId: conformanceHistoryRead
      summary: KV-backed time-series of cert scores for a URL
      description: Returns the 365-entry capped history per URL. Pass ?refresh=1 to run the certifier first + append a new point. 90-day TTL.
      tags:
        - discovery
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            format: uri
        - name: refresh
          in: query
          required: false
          schema:
            type: string
            enum:
              - "1"
      responses:
        "200":
          description: History JSON
          content:
            "application/json":
              schema:
                type: object
    post:
      operationId: conformanceHistoryAppend
      summary: "Run the certifier + append a new point to the URL's history"
      tags:
        - discovery
      parameters:
        - name: url
          in: query
          required: false
          schema:
            type: string
            format: uri
      responses:
        "200":
          description: Updated history JSON
  "/api/auto-monitor":
    get:
      operationId: autoMonitor
      summary: Daily Vercel cron — poll all /registro entries + populate conformance-history
      description: Runs the certifier against each live /registro URL + appends each result to its conformance-history. Optional CRON_SECRET auth.
      tags:
        - discovery
      responses:
        "200":
          description: Run summary JSON
  "/api/rfc-003-envelope":
    get:
      operationId: rfc003Envelope
      summary: Generate the RFC-003 cross-jurisdictional audit envelope for a session
      description: "Wraps the session's RFC-004 entries with RFC-003 issuer metadata + optional externalReferences to a counterpart. 30-day expiry."
      tags:
        - audit
      parameters:
        - name: sessionId
          in: query
          required: false
          schema:
            type: string
        - name: counterpart
          in: query
          required: false
          schema:
            type: string
        - name: counterpartSession
          in: query
          required: false
          schema:
            type: string
        - name: linkType
          in: query
          required: false
          schema:
            type: string
            enum:
              - ap2-mandate
              - acp-checkout
              - mcp
              - manual
      responses:
        "200":
          description: Envelope JSON
  "/api/stats":
    get:
      operationId: stats
      summary: Aggregate live stats (npm, GitHub, artifact counts, conformance)
      description: Single JSON with npm download counts, GitHub stars/forks, RFC + schema + test-vectors + recipe + test-file counts, plus live cert score and count of sociedades at 100/100. Cached 6h.
      tags:
        - discovery
      responses:
        "200":
          description: Stats JSON
  "/.well-known/agents.json":
    get:
      operationId: agentsManifest
      summary: RFC-002 v1 discovery manifest
      description: issuer + endpoints + rfcConformance + auditEndpoints, agents.md-v1 compatible.
      tags:
        - discovery
      responses:
        "200":
          description: Manifest JSON
  "/.well-known/sociedad-ia/verify-key":
    get:
      operationId: verifyKey
      summary: RFC-004 § 5 challenge-response HMAC key-possession proof
      description: Send a 16-128 hex challenge; server returns HMAC-SHA256(secret, challenge) as response + a stable keyFingerprint. Proves the server holds the AUDIT_HMAC_SECRET without revealing it.
      tags:
        - audit
      parameters:
        - name: challenge
          in: query
          required: true
          schema:
            type: string
            pattern: "^[0-9a-fA-F]{16,128}$"
      responses:
        "200":
          description: Challenge-response JSON
  "/.well-known/sociedad-ia/keys":
    get:
      operationId: keys
      summary: RFC-005 § 4 Ed25519 public-keys publication
      description: "Returns the sociedad-IA's Ed25519 public keys (SPKI base64url + raw hex) with keyId + validFrom/validUntil."
      tags:
        - audit
      responses:
        "200":
          description: Keys JSON
components:
  schemas:
    AuditEntry:
      type: object
      description: RFC-004 v1 operational-log entry. See /rfcs/004.
      required:
        - id
        - sessionId
        - ts
        - tool
        - governance
        - input
        - hmac
      properties:
        id:
          type: string
          description: Stable id. ISO-8601 UTC + nonce.
          example: "2026-05-11T14:23:01.512Z-a1b2c3d4"
        sessionId:
          type: string
          pattern: "^[A-Za-z0-9_-]{8,64}$"
        ts:
          type: string
          format: date-time
        tool:
          type: string
          description: Dotted tool path. E.g. mercadopago.preapproval.create.
        governance:
          type: string
          enum:
            - algorithm-only
            - audit-logged
            - mocked-upstream
            - requires-confirmation
        input: {}
        output: {}
        errored:
          type: boolean
        durationMs:
          type: integer
        hmac:
          type:
            - string
            - "null"
          pattern: "^sha256:[0-9a-f]{64}$"
    AuditPayload:
      type: object
      properties:
        sessionId:
          type: string
        entries:
          type: array
          items:
            "$ref": "#/components/schemas/AuditEntry"
        total:
          type: integer
        verified:
          type: integer
        tampered:
          type: integer
        hmacWired:
          type: boolean
        backend:
          type: string
          enum:
            - vercel-kv
            - in-memory
    IncorporateInput:
      type: object
      required:
        - denominacion
        - tipo
        - capitalSocial
        - objeto
      properties:
        denominacion:
          type: string
          minLength: 3
          maxLength: 200
        tipo:
          type: string
          enum:
            - SAS
            - SRL
            - SA
            - SOCIEDAD-IA
        capitalSocial:
          type: integer
          minimum: 1
        objeto:
          type: string
          minLength: 20
        representante:
          type: object
          properties:
            nombre:
              type: string
            cuit:
              type: string
              pattern: "^\\d{2}-\\d{8}-\\d$"
        emailContacto:
          type: string
          format: email
        piezas:
          type: array
          items:
            type: string
        sessionId:
          type: string
          pattern: "^[A-Za-z0-9_-]{8,64}$"
    IncorporateResult:
      type: object
      properties:
        sessionId:
          type: string
        files:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              content:
                type: string
