{
  "openapi": "3.1.0",
  "info": {
    "title": "COD PRO Agent API",
    "version": "1.0.0",
    "description": "Scoped access for your own AI agents and scripts to your COD PRO store. One endpoint; name a tool and pass its arguments. The store is always taken from the key, never from the request. Guide: https://codpro.app/developers/api-quickstart",
    "contact": {
      "email": "info@codpro.app",
      "url": "https://codpro.app/developers"
    }
  },
  "servers": [
    {
      "url": "https://codpro.khaalti.app"
    }
  ],
  "security": [
    {
      "agentKey": []
    }
  ],
  "paths": {
    "/api/agent/v1/call": {
      "post": {
        "operationId": "callTool",
        "summary": "Call one COD PRO tool",
        "description": "Each tool needs a scope on the key: capabilities (none), order_summary / order_messages / recent_events (read:orders), customer_profile (read:customers), order_stats (read:stats), wallet_summary (read:wallet), configuration_summary / precheckout_status (read:configuration), trigger_verification_send (send:otp, uses wallet credit), order_decision / release_hold (write:orders), update_settings / update_precheckout (write:configuration), set_app_paused (control:pause). Rate limit: 60 requests a minute per key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "tool"
                ],
                "properties": {
                  "tool": {
                    "type": "string",
                    "enum": [
                      "capabilities",
                      "order_summary",
                      "order_messages",
                      "recent_events",
                      "customer_profile",
                      "order_stats",
                      "wallet_summary",
                      "configuration_summary",
                      "precheckout_status",
                      "trigger_verification_send",
                      "order_decision",
                      "release_hold",
                      "update_settings",
                      "update_precheckout",
                      "set_app_paused"
                    ]
                  },
                  "arguments": {
                    "type": "object",
                    "description": "Tool arguments, e.g. {\"order_id\": \"1042\"} for order_summary."
                  }
                }
              },
              "examples": {
                "orderSummary": {
                  "value": {
                    "tool": "order_summary",
                    "arguments": {
                      "order_id": "1042"
                    }
                  }
                },
                "capabilities": {
                  "value": {
                    "tool": "capabilities",
                    "arguments": {}
                  }
                },
                "updatePrecheckout": {
                  "summary": "Verify before checkout + Form Builder buttons (write:configuration)",
                  "description": "Allowed settings: channels, language, collect_address, phone_countries, product_display, cod_label, hide_buy_now, hide_add_to_cart, cod_style (theme|filled|outline), cod_note_on, cod_note, cod_sticky, button_order (the three of cod, cart, buy in the order they appear). Unknown keys are refused.",
                  "value": {
                    "tool": "update_precheckout",
                    "arguments": {
                      "settings": {
                        "cod_label": "Buy with Cash on Delivery",
                        "cod_style": "filled",
                        "button_order": [
                          "cod",
                          "cart",
                          "buy"
                        ],
                        "hide_buy_now": false,
                        "cod_sticky": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result as JSON."
          },
          "403": {
            "description": "The key is not granted that capability."
          },
          "404": {
            "description": "Order not found."
          },
          "422": {
            "description": "Invalid tool or arguments."
          },
          "429": {
            "description": "Too many requests or sends; wait a minute."
          },
          "501": {
            "description": "Tool not implemented yet."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "agentKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An Agent API key created in COD PRO."
      }
    }
  }
}