{
  "openapi": "3.1.0",
  "info": {
    "title": "Agonic kit quotes and order drafts",
    "version": "1.0.0",
    "summary": "Price an Agonic PCB verification kit and start an order that the customer confirms by email.",
    "description": "Agonic builds a custom verification kit for one revision of a circuit board: an interposer board and a probe dock made for that board. The bench instruments plug into one end, the board into the other, and an AI agent runs the tests and writes the verification report.\n\nThese endpoints are for programs: AI agents, scripts and tools. `GET /api/quote` prices a kit from its counts and stores nothing. `POST /api/order-draft` starts an order: it does not place one. Agonic emails the customer a link, and the order is placed only when they open it and press Place order.\n\nEvery price is an estimate for custom hardware built for one board revision. Agonic confirms it after engineering review of the design files, and the customer approves any change before the build. Design files are covered by the Design Data Terms (https://agonicai.com/legal/design-data).\n\nThe same three operations are offered to MCP clients at https://agonicai.com/mcp (Streamable HTTP, no account). `POST /api/order` is the endpoint of the order form on the site itself; it needs a browser check and is not described here.",
    "contact": {
      "name": "Agonic",
      "email": "engineering@agonicai.com",
      "url": "https://agonicai.com"
    },
    "termsOfService": "https://agonicai.com/terms"
  },
  "servers": [
    {
      "url": "https://agonicai.com"
    }
  ],
  "externalDocs": {
    "description": "For AI agents: how to quote and order",
    "url": "https://agonicai.com/agents"
  },
  "paths": {
    "/api/quote": {
      "get": {
        "operationId": "getKitQuote",
        "summary": "Price a kit from its counts",
        "description": "The same arithmetic as the quote form on the home page. No account, no personal data, nothing stored. May be called from any origin.",
        "parameters": [
          {
            "name": "tp",
            "in": "query",
            "required": true,
            "description": "Test points: signal and power nets to probe. Ground probes are included. High-voltage and high-current points are counted here too.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9999
            }
          },
          {
            "name": "inst",
            "in": "query",
            "required": true,
            "description": "Instrument connections: one per bench port that plugs in (a supply channel, a multimeter, each scope channel, an analyzer port, a programmer).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9999
            }
          },
          {
            "name": "flex",
            "in": "query",
            "required": false,
            "description": "Ribbon (IDC) and flex (FFC or FPC) connectors on the board that the dock reaches signals through.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9999,
              "default": 0
            }
          },
          {
            "name": "hv",
            "in": "query",
            "required": false,
            "description": "Test points that can exceed 60 V DC. 60 V is the line used for pricing, not a rating.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9999,
              "default": 0
            }
          },
          {
            "name": "hc1",
            "in": "query",
            "required": false,
            "description": "Points where the dock supplies or loads the board at 2 to 10 A. Points that are only measured do not count.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9999,
              "default": 0
            }
          },
          {
            "name": "hc2",
            "in": "query",
            "required": false,
            "description": "Points where the dock supplies or loads the board above 10 A.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9999,
              "default": 0
            }
          },
          {
            "name": "hs",
            "in": "query",
            "required": false,
            "description": "Signals probed through coax (a differential pair is 2). Do not also count these as test points.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9999,
              "default": 0
            }
          },
          {
            "name": "rf",
            "in": "query",
            "required": false,
            "description": "RF ports, each brought out on its own SMA. Do not also count these as test points.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9999,
              "default": 0
            }
          },
          {
            "name": "side",
            "in": "query",
            "required": false,
            "description": "Two-sided probing: true when more than 10 points are on the second side of the board, which adds a second probe plate. Accepts 1, true, yes or on.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "true",
                "false",
                "yes",
                "no",
                "on",
                "off"
              ],
              "default": "0"
            }
          },
          {
            "name": "coupon",
            "in": "query",
            "required": false,
            "description": "A coupon code, in any case. An unknown code is not an error: the answer carries the kit price and a `couponError` sentence.",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The quote.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "operationId": "postKitQuote",
        "summary": "Price a kit from its counts (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/Counts"
                      },
                      {
                        "type": "object",
                        "properties": {
                          "coupon": {
                            "type": "string"
                          }
                        }
                      }
                    ]
                  },
                  {
                    "type": "object",
                    "required": [
                      "counts"
                    ],
                    "properties": {
                      "counts": {
                        "$ref": "#/components/schemas/Counts"
                      },
                      "coupon": {
                        "type": "string"
                      }
                    }
                  }
                ]
              },
              "example": {
                "tp": 50,
                "inst": 8,
                "coupon": "EARLYPARTNER"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The quote.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/order-draft": {
      "post": {
        "operationId": "createOrderDraft",
        "summary": "Start an order for the customer to confirm by email",
        "description": "Makes a draft, not an order. The server prices each kit from its counts (any amount a client sends is ignored), stores the design files, and emails the customer a link. The order is placed only when the customer opens the link and presses Place order. The link is never returned to the caller. A draft expires after 7 days.\n\nSend `order` as a text part before the file parts. Name file parts `files` for one kit, or `files:<kit id>` (for example `files:kit-1`) for several.\n\nLimits: at least 1 and at most 20 files per kit, at most 10 kits, 90 MB for all files in one draft. One coupon per order, on its first kit; an unknown coupon code is an error. Per day: 2 drafts per customer email address and 5 per source address. Text fields and file names may not contain a web address. Do not send ITAR-controlled or EAR-listed designs.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "order",
                  "files"
                ],
                "x-max-total-file-bytes": 94371840,
                "properties": {
                  "order": {
                    "$ref": "#/components/schemas/DraftOrder"
                  },
                  "files": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 20,
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "The design files for the kit: schematic and layout for one board revision; a BOM is optional. Any file type; zip a folder."
                  }
                }
              },
              "encoding": {
                "order": {
                  "contentType": "application/json"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The draft was stored and the customer was emailed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Draft"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/order-confirm": {
      "get": {
        "operationId": "reviewOrderDraft",
        "summary": "The page a customer reviews a draft on",
        "description": "For the customer, in a browser, from the emailed link. Shows the kit, the price and the button that places the order. It never places an order itself. Not for agents: the link goes only to the customer’s inbox.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DraftId"
          },
          {
            "$ref": "#/components/parameters/DraftToken"
          }
        ],
        "responses": {
          "200": {
            "description": "The review page, or the order number if the draft was already placed.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "The link is not valid or has expired.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "placeOrderFromDraft",
        "summary": "Place the order (the page’s button)",
        "description": "Sent by the button on the review page. Places the order once; a repeat shows the same order number.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DraftId"
          },
          {
            "$ref": "#/components/parameters/DraftToken"
          }
        ],
        "responses": {
          "200": {
            "description": "A page with the order number.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "The link is not valid or has expired.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "The order could not be placed just now; the draft is kept.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "DraftId": {
        "name": "d",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[0-9A-HJKMNP-TV-Z]{16}$"
        }
      },
      "DraftToken": {
        "name": "t",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{43}$"
        }
      }
    },
    "responses": {
      "Error": {
        "description": "The request was refused. `message` says how to put it right.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Counts": {
        "type": "object",
        "description": "What the kit has to reach on the board. `tp` and `inst` are required; the rest default to 0. Each count has a short key and a readable name; send either.",
        "properties": {
          "tp": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9999,
            "description": "Test points: signal and power nets to probe. Ground probes are included. High-voltage and high-current points are counted here too."
          },
          "test_points": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9999,
            "description": "The same count as `tp`, by its readable name. Send one or the other."
          },
          "inst": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9999,
            "description": "Instrument connections: one per bench port that plugs in (a supply channel, a multimeter, each scope channel, an analyzer port, a programmer)."
          },
          "instrument_connections": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9999,
            "description": "The same count as `inst`, by its readable name. Send one or the other."
          },
          "flex": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "Ribbon (IDC) and flex (FFC or FPC) connectors on the board that the dock reaches signals through."
          },
          "flex_connectors": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "The same count as `flex`, by its readable name. Send one or the other."
          },
          "hv": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "Test points that can exceed 60 V DC. 60 V is the line used for pricing, not a rating."
          },
          "high_voltage_points": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "The same count as `hv`, by its readable name. Send one or the other."
          },
          "hc1": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "Points where the dock supplies or loads the board at 2 to 10 A. Points that are only measured do not count."
          },
          "high_current_points_2_to_10a": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "The same count as `hc1`, by its readable name. Send one or the other."
          },
          "hc2": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "Points where the dock supplies or loads the board above 10 A."
          },
          "high_current_points_above_10a": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "The same count as `hc2`, by its readable name. Send one or the other."
          },
          "hs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "Signals probed through coax (a differential pair is 2). Do not also count these as test points."
          },
          "high_speed_signals": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "The same count as `hs`, by its readable name. Send one or the other."
          },
          "rf": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "RF ports, each brought out on its own SMA. Do not also count these as test points."
          },
          "rf_ports": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "The same count as `rf`, by its readable name. Send one or the other."
          },
          "side": {
            "type": "boolean",
            "description": "Two-sided probing: true when more than 10 points are on the second side of the board, which adds a second probe plate."
          },
          "two_sided": {
            "type": "boolean",
            "description": "The same as `side`, by its readable name."
          }
        },
        "anyOf": [
          {
            "required": [
              "tp",
              "inst"
            ]
          },
          {
            "required": [
              "test_points",
              "instrument_connections"
            ]
          },
          {
            "required": [
              "tp",
              "instrument_connections"
            ]
          },
          {
            "required": [
              "test_points",
              "inst"
            ]
          }
        ]
      },
      "Line": {
        "type": "object",
        "required": [
          "label",
          "detail",
          "amount"
        ],
        "properties": {
          "label": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "amount": {
            "type": "number"
          }
        }
      },
      "Quote": {
        "type": "object",
        "required": [
          "ok",
          "currency",
          "counts",
          "lines",
          "estimate",
          "coupon",
          "total",
          "priceNote",
          "prefillUrl",
          "links"
        ],
        "properties": {
          "ok": {
            "const": true
          },
          "currency": {
            "const": "USD"
          },
          "counts": {
            "type": "object",
            "description": "The counts the price was worked out from, by their short keys."
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Line"
            }
          },
          "estimate": {
            "type": "number",
            "description": "The kit price before any coupon."
          },
          "coupon": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "code",
                  "percent",
                  "limit",
                  "discount"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "percent": {
                    "type": "number"
                  },
                  "limit": {
                    "type": "number"
                  },
                  "discount": {
                    "type": "number"
                  }
                }
              }
            ]
          },
          "couponError": {
            "type": "string",
            "description": "Present when the coupon code sent is not one we know."
          },
          "total": {
            "type": "number",
            "description": "The quote: the kit price less the coupon. An estimate until engineering review."
          },
          "priceNote": {
            "type": "string"
          },
          "notIncluded": {
            "type": "string"
          },
          "prefillUrl": {
            "type": "string",
            "format": "uri",
            "description": "Opens the order form on agonicai.com with these counts and this coupon filled in."
          },
          "links": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      },
      "Address": {
        "type": "object",
        "required": [
          "line1",
          "city",
          "country"
        ],
        "properties": {
          "line1": {
            "type": "string",
            "maxLength": 120
          },
          "line2": {
            "type": "string",
            "maxLength": 120
          },
          "city": {
            "type": "string",
            "maxLength": 80
          },
          "region": {
            "type": "string",
            "maxLength": 80,
            "description": "State, province or region. For the United States and Canada, the two-letter code (required)."
          },
          "postal_code": {
            "type": "string",
            "maxLength": 20,
            "description": "Required and checked for the United States and Canada."
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "Two-letter ISO code of a country on the order form: every country and territory except CU, IR, KP and SY."
          }
        }
      },
      "Customer": {
        "type": "object",
        "required": [
          "name",
          "email",
          "company",
          "address"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 120
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "description": "The customer’s own address. The confirmation link is sent here."
          },
          "company": {
            "type": "string",
            "maxLength": 120
          },
          "phone": {
            "type": "string",
            "maxLength": 40
          },
          "turnaround": {
            "type": "string",
            "enum": [
              "1 week",
              "2 weeks",
              "4 weeks",
              "Flexible"
            ],
            "default": "Flexible",
            "description": "When the customer needs the kit. Agonic confirms the ship date with the order."
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "DraftKit": {
        "type": "object",
        "required": [
          "counts"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{0,31}$",
            "description": "Names the kit’s file parts (`files:<id>`). Defaults to kit-1, kit-2, …"
          },
          "counts": {
            "$ref": "#/components/schemas/Counts"
          },
          "coupon": {
            "type": "string"
          }
        }
      },
      "DraftOrder": {
        "type": "object",
        "required": [
          "customer"
        ],
        "description": "One kit: `counts` (and `coupon`). Several kits: `items`.",
        "properties": {
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "counts": {
            "$ref": "#/components/schemas/Counts"
          },
          "coupon": {
            "type": "string",
            "description": "One per order, applied to its first kit."
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/DraftKit"
            }
          }
        },
        "example": {
          "customer": {
            "name": "Ada Example",
            "email": "ada@example.com",
            "company": "Example Robotics",
            "turnaround": "2 weeks",
            "address": {
              "line1": "1 Example Way",
              "city": "San Francisco",
              "region": "CA",
              "postal_code": "94103",
              "country": "US"
            }
          },
          "counts": {
            "tp": 50,
            "inst": 8
          },
          "coupon": "EARLYPARTNER"
        }
      },
      "Draft": {
        "type": "object",
        "required": [
          "ok",
          "draftId",
          "expiresAt",
          "emailed",
          "total",
          "message"
        ],
        "properties": {
          "ok": {
            "const": true
          },
          "draftId": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "emailed": {
            "type": "boolean",
            "description": "True when the confirmation email was accepted for delivery."
          },
          "currency": {
            "const": "USD"
          },
          "total": {
            "type": "number"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "estimate": {
                  "type": "number"
                },
                "coupon": {
                  "type": "string"
                },
                "discount": {
                  "type": "number"
                },
                "total": {
                  "type": "number"
                },
                "files": {
                  "type": "integer"
                }
              }
            }
          },
          "priceNote": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "ok",
          "error",
          "message"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "string",
            "description": "A short code, for example missing_count, invalid_coupon, missing_file, rate_limited."
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
