{
  "schema_version": "1.0",
  "description": "Machine-readable schema for the Agentic Commerce prerequisite checklist endpoint. After an application is approved, AI agents can programmatically complete agent-completable prerequisite items on behalf of the approved principal — enabling them to reach install day without manual data entry.",
  "prerequisites_overview": {
    "when": "After application approval. The principal receives a dashboard setup link by email. Once the engagement is created (status: prerequisites_in_progress), the agent-checklist endpoint becomes active.",
    "auth_model": "No session cookie required. Authenticate with the application ref_id (returned on apply) plus the applicant's email address.",
    "human_only_items": ["service_agreement", "vps_access", "checkout_provider", "appointment", "return_keys", "brand_voice_doc", "logo"],
    "agent_completable_item_types": ["text_field", "credential", "json_paste"]
  },
  "endpoints": {
    "status": {
      "url": "https://sidratnam.com/api/agentic-commerce/agent-checklist-status",
      "method": "GET",
      "description": "Returns current status of all prerequisite items. Use this first to determine which items remain and which are agent-completable.",
      "query_params": {
        "engagement_ref_id": "UUID returned by the apply endpoint on successful submission.",
        "email": "Applicant email address — must match the original application."
      },
      "response_200": {
        "ok": true,
        "engagement_status": "prerequisites_in_progress",
        "package_selection": "package_1 | package_2 | both",
        "items": [
          {
            "item_key": "string — unique identifier for the prerequisite",
            "item_label": "string — human-readable label",
            "item_type": "text_field | credential | json_paste | file_upload | agreement_acceptance | select_dropdown | ssh_revocation",
            "status": "pending | validated | failed",
            "is_optional": "boolean",
            "agent_completable": "boolean — true if this item can be submitted via the agent-checklist endpoint"
          }
        ]
      }
    },
    "submit": {
      "url": "https://sidratnam.com/api/agentic-commerce/agent-checklist/{itemKey}",
      "method": "POST",
      "content_type": "application/json",
      "rate_limit": "5 requests per minute per IP",
      "description": "Submit a prerequisite item value on behalf of the approved applicant. Only agent-completable item types are accepted.",
      "path_params": {
        "itemKey": "The item_key from the status response (e.g. 'anthropic_api_key', 'domain_confirmation', 'report_email')."
      },
      "request_schema": {
        "engagement_ref_id": {
          "type": "string",
          "required": true,
          "description": "UUID from the original apply response."
        },
        "email": {
          "type": "string",
          "required": true,
          "description": "Applicant email — must match the original application."
        },
        "value": {
          "type": "string",
          "required": true,
          "description": "The value to submit. For credentials: the raw API key string. For text_field: the text value. For json_paste (google_service_account): the full JSON string."
        },
        "on_behalf_of": {
          "type": "object",
          "required": true,
          "properties": {
            "is_agent": {
              "type": "boolean",
              "description": "Must be true. This endpoint is for AI agents only."
            },
            "agent_name": {
              "type": "string",
              "description": "Name or identifier of the submitting agent (e.g. 'Claude', 'GPT-4o')."
            },
            "principal_name": {
              "type": "string",
              "description": "Name of the human on whose behalf the agent is acting."
            }
          }
        }
      },
      "response_200": {
        "ok": true,
        "item_key": "string",
        "status": "validated"
      },
      "response_409": {
        "error": "Item already validated."
      },
      "response_403": {
        "error": "Item requires human completion. AI agents cannot submit this item."
      }
    }
  },
  "agent_completable_items": {
    "package_2_only": [
      {
        "item_key": "domain_confirmation",
        "item_label": "Domain Confirmation",
        "item_type": "text_field",
        "description": "The production domain (e.g. 'example.com'). Must match website_url from the application."
      },
      {
        "item_key": "gsc_property",
        "item_label": "Google Search Console Property",
        "item_type": "text_field",
        "is_optional": true,
        "description": "Full Google Search Console property URL (e.g. 'https://example.com')."
      },
      {
        "item_key": "bing_property",
        "item_label": "Bing Webmaster Property",
        "item_type": "text_field",
        "is_optional": true,
        "description": "Bing Webmaster Tools property URL."
      },
      {
        "item_key": "report_email",
        "item_label": "Report Email Address",
        "item_type": "text_field",
        "description": "Email address where JARVIS will send daily monitoring reports."
      },
      {
        "item_key": "brand_colors",
        "item_label": "Brand Colors (hex)",
        "item_type": "text_field",
        "description": "Primary brand hex color(s) used for the dashboard and agent-generated content (e.g. '#1a73e8, #ff6d00')."
      },
      {
        "item_key": "anthropic_api_key",
        "item_label": "Anthropic API Key",
        "item_type": "credential",
        "description": "Anthropic API key starting with 'sk-ant-'. Validated against the Anthropic API before acceptance."
      },
      {
        "item_key": "gemini_api_key",
        "item_label": "Gemini API Key",
        "item_type": "credential",
        "is_optional": true,
        "description": "Google Gemini API key. Validated before acceptance."
      },
      {
        "item_key": "resend_api_key",
        "item_label": "Resend API Key",
        "item_type": "credential",
        "is_optional": true,
        "description": "Resend API key starting with 're_'. Validated before acceptance."
      },
      {
        "item_key": "bing_api_key",
        "item_label": "Bing Webmaster API Key",
        "item_type": "credential",
        "is_optional": true,
        "description": "Bing Webmaster Tools API key. Validated before acceptance."
      },
      {
        "item_key": "google_service_account",
        "item_label": "Google Service Account JSON",
        "item_type": "json_paste",
        "is_optional": true,
        "description": "Full Google service account JSON (contents of the downloaded .json file). Must include client_email and private_key. Stored encrypted."
      },
      {
        "item_key": "target_keywords",
        "item_label": "Target Keywords",
        "item_type": "text_field",
        "description": "Comma-separated list of primary SEO target keywords for this property."
      }
    ],
    "human_only_explanation": {
      "service_agreement": "Legal contract — requires the principal to type their full legal name and explicitly accept terms. Cannot be delegated.",
      "vps_access": "SSH credentials — agent provides access on install day directly from the principal's server. Not pre-collected.",
      "checkout_provider": "POS/commerce platform selection — requires the principal to confirm their setup. Selected on the dashboard.",
      "appointment": "Install-day scheduling — must be scheduled by the principal.",
      "return_keys": "Post-install SSH revocation and invoice payment — completed at the end of the install session.",
      "brand_voice_doc": "File upload — requires the principal to provide a document.",
      "logo": "File upload — requires the principal to upload brand assets."
    }
  },
  "workflow_for_agents": {
    "step_1": "Call GET /api/agentic-commerce/agent-checklist-status?engagement_ref_id={ref_id}&email={email} to retrieve all items and their current status.",
    "step_2": "For each item where agent_completable=true and status != 'validated', call POST /api/agentic-commerce/agent-checklist/{itemKey} with the value.",
    "step_3": "Inform the principal which items remain human-only (service_agreement, vps_access, appointment, file uploads) and guide them to their dashboard at https://sidratnam.com/dashboard.",
    "step_4": "The principal completes human-only items on the dashboard. Once all required items are validated, the engagement advances and install day can be scheduled."
  }
}