openapi: 3.1.0
info:
  title: Agentics API
  version: 1.0.0
  description: Trust receipts and governance for AI agents.
  contact: { email: developers@agentics.you, url: https://agentics.you/developers/ }
  license: { name: Apache-2.0 }
servers:
  - url: https://agentics.you
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: "ak_…" }
  schemas:
    ReceiptIn:
      type: object
      required: [event_id, agent, task]
      properties:
        event_id: { type: string }
        agent:
          type: object
          properties:
            external_id: { type: string }
            foundation_model: { type: string }
            model_version: { type: string }
            system_prompt: { type: string }
            tool_manifest: {}
            scope: { type: array, items: { type: string } }
        task:
          type: object
          properties:
            task_id: { type: string }
            started_at: { type: string, format: date-time }
            finished_at: { type: string, format: date-time }
            outcome: { type: string, enum: [success, partial, failed] }
            cost_usd: { type: number }
            tokens_in: { type: integer }
            tokens_out: { type: integer }
            scope_used: { type: array, items: { type: string } }
            inputs: { type: string }
            outputs: { type: string }
            metadata: { type: object, additionalProperties: true }
paths:
  /api/sdk/ingest:
    post:
      summary: Ingest a receipt (single or {batch:[...]})
      requestBody: { required: true, content: { application/json: { schema: { oneOf: [ { $ref: "#/components/schemas/ReceiptIn" }, { type: object, properties: { batch: { type: array, items: { $ref: "#/components/schemas/ReceiptIn" } } } } ] } } } }
      responses: { "200": { description: ok } }
  /api/agents-e:
    get: { summary: List enterprise agents, responses: { "200": { description: ok } } }
  /api/policies/evaluate:
    post: { summary: Evaluate a policy decision, responses: { "200": { description: ok } } }
  /api/risk:
    get: { summary: List risks }
    post: { summary: Create risk }
  /api/incidents:
    get: { summary: List incidents }
    post: { summary: Open incident }
  /api/approvals:
    get: { summary: List approvals }
    post: { summary: Open approval }
  /api/evidence:
    get: { summary: List evidence packs }
    post: { summary: Generate evidence pack }
  /api/redteam:
    get: { summary: List runs }
    post: { summary: Start run }
  /api/drift/{agent_handle}:
    get: { summary: Drift per agent }
  /api/bias/{agent_handle}:
    get: { summary: Bias per agent }
  /api/aibom/{agent_id}:
    get: { summary: CycloneDX 1.6 AI-BOM }
  /api/api-keys:
    get: { summary: List keys }
    post: { summary: Create key }
  /api/webhooks:
    get: { summary: List webhooks }
    post: { summary: Create webhook }
  /api/trust/status:
    get: { summary: Public status, security: [] }
  /api/trust/agents:
    get: { summary: Public agent directory, security: [] }
  /api/trust/verify/{hash}:
    get: { summary: Verify a receipt hash, security: [] }
  /api/trust/certifications:
    get: { summary: Public certifications, security: [] }
  /api/intelligence/packs:
    get: { summary: Industry packs }
  /api/intelligence/benchmarks:
    get: { summary: K-anonymized benchmarks }
  /api/intelligence/threats:
    get: { summary: Threat feed }
  /api/insurance/partners:
    get: { summary: Insurance partners, security: [] }
  /api/insurance/refer:
    post: { summary: Refer to broker, security: [] }
  /api/operators:
    get: { summary: List operators }
  /api/operators/apply:
    post: { summary: Apply to be an operator, security: [] }
  /api/console/summary:
    get: { summary: Per-tenant console rollup }
  /api/exports:
    post: { summary: Export job }
  /api/litigation/holds:
    get: { summary: List holds }
    post: { summary: Create hold }
  /api/retention:
    get: { summary: Get retention }
    patch: { summary: Patch retention }
  /api/rtbf:
    post: { summary: Right-to-be-forgotten request, security: [] }
  /api/mcp/manifest:
    get: { summary: MCP manifest, security: [] }
  /api/mcp/jsonrpc:
    post: { summary: MCP JSON-RPC endpoint }
  /api/gateway/proxy:
    post: { summary: Gateway proxy callback (LiteLLM/Portkey/Helicone/etc.) }
  /api/otel/ingest:
    post: { summary: OTLP/JSON GenAI ingest }
  /api/receivers/{vendor}:
    post: { summary: SaaS receivers (Claude Enterprise / OpenAI Enterprise / Copilot / …) }
  /api/casb/{vendor}:
    post: { summary: CASB ingest (Netskope / Zscaler / Defender / …) }
  /api/sso/saml/metadata:
    get: { summary: SP metadata, security: [] }
  /api/sso/saml/acs:
    post: { summary: SAML assertion consumer, security: [] }
  /api/sso/oidc/login:
    get: { summary: OIDC Auth Code start, security: [] }
  /api/sso/oidc/callback:
    get: { summary: OIDC callback, security: [] }
  /api/scim/v2/Users:
    get: { summary: SCIM Users list }
    post: { summary: SCIM Users create }
  /api/scim/v2/Groups:
    get: { summary: SCIM Groups list }
  /api/admin/flags:
    get: { summary: List feature flags }

  # ── Cornerstone build (2026-05-19) ───────────────────────────────────────
  # Public, free-tier read endpoints. Marks run on a deterministic model
  # today; the response shapes are the stable contract.
  /v1/terminal:
    get: { summary: "Terminal market-data payload — AGNX indices, capability tickers, agent roster, counterparties", security: [] }
  /v1/agn-id:
    get:
      summary: "List issued AGN-IDs, or resolve a single one with ?id=AGN-XXXX-XXXX-XXXX"
      security: []
      parameters:
        - { in: query, name: id, schema: { type: string, pattern: "^AGN-[0-9A-Z]{4}-[0-9A-Z]{4}-[0-9A-Z]{4}$" } }
    post:
      summary: "Issue an AGN-ID for a key binding (idempotent; content-bound)"
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                public_key:  { type: string, description: "Preferred binding (e.g. ed25519:…)" }
                vendor:      { type: string }
                agent_name:  { type: string }
  /v1/standards/disputes:
    get: { summary: "Dispute-resolution case law + stats", security: [] }
  /v1/discovery:
    get: { summary: "Public Discovery directory — agents, vendors, sectors, transaction tape", security: [] }
  /v1/trading:
    get: { summary: "Trading desk state — RFQs, fills, auctions, forwards, SLA instruments, smart-order routing", security: [] }
  /v1/attribution:
    get: { summary: "Performance attribution — per-agent P&L, ROI waterfall, per-workflow margin", security: [] }
  /v1/treasury:
    get: { summary: "Treasury operations — multi-rail balances, reconciliation, FX, float, working capital", security: [] }
  /v1/terminal/entitlement:
    get: { summary: "Resolve plan + gating state for the current session", security: [] }
  /v1/terminal/watchlist:
    get:    { summary: "List the signed-in user's Terminal watchlist (cookie auth)" }
    post:   { summary: "Add a watchlist entry { kind: tickers|agents|vendors, ref_id }" }
    delete: { summary: "Remove via ?kind=&ref_id=" }
  /v1/terminal/alerts:
    get:    { summary: "List the signed-in user's threshold alerts (cookie auth)" }
    post:   { summary: "Create an alert { id?, scope, target, metric, op:>|<, value }" }
    delete: { summary: "Remove via ?id=" }
  /v1/embed/agnx.svg:
    get:
      summary: "Embeddable AGNX index SVG widget"
      security: []
      parameters:
        - { in: query, name: theme, schema: { type: string, enum: [dark, light] } }
        - { in: query, name: w,     schema: { type: integer, minimum: 160, maximum: 480 } }
        - { in: query, name: h,     schema: { type: integer, minimum: 60,  maximum: 160 } }
      responses: { "200": { description: SVG, content: { image/svg+xml: {} } } }
  /v1/embed/ticker.svg:
    get:
      summary: "Embeddable capability-ticker SVG widget"
      security: []
      parameters:
        - { in: query, name: symbol, required: true, schema: { type: string } }
        - { in: query, name: theme,  schema: { type: string, enum: [dark, light] } }
        - { in: query, name: w,      schema: { type: integer, minimum: 160, maximum: 480 } }
        - { in: query, name: h,      schema: { type: integer, minimum: 60,  maximum: 160 } }
      responses: { "200": { description: SVG, content: { image/svg+xml: {} } } }
  /v1/receipts:
    post:
      summary: "Native receipt ingestion (single task_receipt; Idempotency-Key required)"
      requestBody: { required: true, content: { application/json: { schema: { $ref: "https://agentics.you/schemas/task_receipt.v1.json" } } } }
  /v1/quickstart-install:
    post: { summary: "One-line agent install — returns a bash script for the wizard", security: [] }
  /v1/me/install-snippet:
    post: { summary: "Render and cache install snippets for an account" }
  /v1/me/platforms:
    post: { summary: "Record platform declarations + capture preferences" }
