Eformogi Agent Protocol API

openapi: 3.2.0
info:
  title: Eformogi Agent Protocol API
  version: 33.5.1
  description: 'Eformogi is a record of learning the student owns, witnessed by the adults who were there, verifiable at one link with no login, and issued by the schools and counselors who hold the learners. The family-issued receipt (`tr_`) is a Witness Transcript. This document describes the machine-readable surface: verification, witness attestation, consent, the agent protocol, and the issuer rail (enrollment, roster, declared courses, and the family side that folds them into the transcript). The open record format itself is published at https://eformogi.com/spec.'
  contact:
    url: https://eformogi.com
  license:
    name: Proprietary
servers:
- url: https://eformogi.com
  description: Production
tags:
- name: Agent Protocol
  description: Machine-readable consent verification, scoped data access, and execution tracing for AI agents and integrations
paths:
  /api/verify-consent:
    get:
      summary: 'Verify a consent grant: check status, authorized fields, duration'
      description: The core agent-facing endpoint. Returns consent status (active/expired/revoked), authorized field categories, purpose, time remaining, and verification provenance summary. Agents call this before reading profile data.
      tags:
      - Agent Protocol
      security:
      - orgApiKey: []
      parameters:
      - name: consent_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
        description: The consent grant ID to verify
      responses:
        '200':
          description: Consent verification result with status, scope, timestamps, and verification summary
        '401':
          description: Invalid or missing API key
        '403':
          description: Consent not active or not authorized
        '404':
          description: Consent grant not found
      operationId: getApiVerifyConsent
      x-operation-id-source: derived
  /api/profile-read:
    get:
      summary: Read profile data authorized by a consent grant
      description: 'Returns profile data filtered to only the categories the consent grant authorizes AND the API key has scope for. Double enforcement: consent scope + API key scope. Proof-minimization at the API level.'
      tags:
      - Agent Protocol
      security:
      - orgApiKey: []
      parameters:
      - name: consent_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: categories
        in: query
        schema:
          type: string
        description: Comma-separated field categories to read. Defaults to all authorized categories.
      responses:
        '200':
          description: Filtered profile data with only authorized categories
        '401':
          description: Invalid or missing API key
        '403':
          description: Requested categories exceed consent or API key scope
        '404':
          description: Consent or profile not found
      operationId: getApiProfileRead
      x-operation-id-source: derived
  /api/agent-action:
    get:
      summary: Query the agent execution trace
      description: 'Returns a log of all agent data access events for the organization. Filterable by consent_id, action type, and time range. Constitutional Rule 6: receipts for everything.'
      tags:
      - Agent Protocol
      security:
      - orgApiKey: []
      parameters:
      - name: consent_id
        in: query
        schema:
          type: string
          format: uuid
      - name: action
        in: query
        schema:
          type: string
      - name: since
        in: query
        schema:
          type: string
          format: date-time
      - name: until
        in: query
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 100
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Paginated list of execution trace entries
      operationId: getApiAgentAction
      x-operation-id-source: derived
    post:
      summary: Log a custom agent action
      description: Institutional systems log their own actions (EMR export, clinical note generation, forwarding) against a consent grant. Creates an auditable receipt.
      tags:
      - Agent Protocol
      security:
      - orgApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: Action name (alphanumeric, dots, underscores)
                  example: export.emr
                consent_id:
                  type: string
                  format: uuid
                details:
                  type: object
                  description: Structured details (max 10KB)
                agent_id:
                  type: string
                  description: Identifier for the agent performing the action
              required:
              - action
      responses:
        '201':
          description: Action logged with trace ID
      operationId: postApiAgentAction
      x-operation-id-source: derived
  /api/mcp:
    post:
      summary: MCP server (JSON-RPC 2.0, streamable HTTP, no SDK)
      description: 'The Model Context Protocol endpoint, hand-rolled JSON-RPC 2.0 over single JSON responses (no SSE stream: a GET whose Accept names text/event-stream is 405, any other GET is a plain self-description; a JSON-RPC batch, an array, is answered as an array; every notifications/* is an empty 202; protocol versions 2024-11-05, 2025-03-26, and 2025-06-18; CORS open to any origin). Two doors on one endpoint. PUBLIC, no login and no API key (engine #6, Sep 2026; rule 8: the protocol is open): initialize, ping, notifications/initialized, and tools/list, plus tools/call for verify_record (verify one receipt id, the same check /verify performs), how_eformogi_works (the thesis sentence and the pricing paragraph, verbatim), and read_spec (read the open record standard published at /spec). AUTHENTICATED, a personal API key sent as `Authorization: Bearer efg_...`: tools/call for read_profile, list_consents, create_consent, check_policy, log_action, search_orgs, reading or acting on a person''s vault data on their behalf; every personal key carries a per-category policy of auto (the agent may read), ask (the person approves first), or never (blocked), and every call is written to the person''s audit trail.'
      tags:
      - Agent Protocol
      security:
      - bearerAuth: []
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  type: string
                  enum:
                  - '2.0'
                id:
                  description: JSON-RPC request id
                method:
                  type: string
                  enum:
                  - initialize
                  - ping
                  - notifications/initialized
                  - tools/list
                  - tools/call
                params:
                  type: object
                  description: 'Method params. For tools/call: { name, arguments }.'
              required:
              - jsonrpc
              - method
      responses:
        '200':
          description: JSON-RPC 2.0 response. A tool denied by policy, or a public tool given an unknown receipt id, returns a result describing the denial, not a transport error.
        '202':
          description: notifications/initialized acknowledged (no body)
        '401':
          description: Missing or invalid personal API key, for a tools/call naming one of the six authenticated tools
        '429':
          description: Rate limited
      operationId: postApiMcp
      x-operation-id-source: derived
  /api/widget:
    get:
      summary: Embeddable intake widget script
      description: Returns a JavaScript snippet that renders a consent intake button or form on any website. Orgs embed this on their site to let families share profiles directly.
      tags:
      - Agent Protocol
      parameters:
      - name: slug
        in: query
        required: true
        schema:
          type: string
        description: Intake link slug
      - name: theme
        in: query
        schema:
          type: string
          enum:
          - light
          - dark
          default: light
      - name: position
        in: query
        schema:
          type: string
          enum:
          - inline
          - floating
          default: inline
      - name: text
        in: query
        schema:
          type: string
        description: Custom button text
      responses:
        '200':
          description: JavaScript widget code
          content:
            application/javascript: {}
      operationId: getApiWidget
      x-operation-id-source: derived
  /api/institutional/api-keys:
    get:
      summary: List org API keys
      description: List all active API keys for the authenticated user's organization. Keys are masked.
      tags:
      - Agent Protocol
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of API keys with scope and usage info
      operationId: getApiInstitutionalApiKeys
      x-operation-id-source: derived
    post:
      summary: Create a scoped org API key
      description: Generate a new API key with optional field-category scoping. The key secret is only shown once.
      tags:
      - Agent Protocol
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
                allowed_categories:
                  type: array
                  items:
                    type: string
                  description: Field categories this key can access. Omit for full access.
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 365
      responses:
        '201':
          description: API key created with secret (shown once)
      operationId: postApiInstitutionalApiKeys
      x-operation-id-source: derived
    delete:
      summary: Revoke an org API key
      tags:
      - Agent Protocol
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: API key revoked
      operationId: deleteApiInstitutionalApiKeys
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase JWT access token
    orgApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Institutional org API key. Use "Bearer efg_org_..." or "Api-Key efg_org_..." header. Keys are scoped to specific data categories.