{
  "openapi": "3.1.0",
  "info": {
    "title": "Atom Backends agent inquiry API",
    "version": "1.0.0",
    "description": "Atom Backends fixes the systems US home-service and trade businesses run on (HVAC, plumbing, electrical, roofing and exterior trades, field service, security and facilities): scheduling, job-to-invoice, reporting and the QuickBooks sync. It finds where finished jobs leak money and hours on the way to cash, then fixes the root cause.\n\nAI agents and assistants can send an inquiry on behalf of a person here. An automated system answers with a machine-readable acknowledgement and the booking link; a person on the Atom Backends team reads every inquiry and answers the contact directly. Nothing is emailed to the contact automatically. Send only what the person agreed to share, and set consent to true only if they agreed to be contacted.\n\nPrivacy: Atom Digital Technologies LLP (England and Wales, OC450214), which operates Atom Backends is responsible for the information an agent sends here. It is used to answer this inquiry, follow up on it and count inquiries, under UK GDPR (Article 6(1)(b) and 6(1)(f)); for contacts in the United States, the applicable state privacy laws. It is not sold. It is kept 12 months from receipt, then deleted; ask privacy@atombackends.com to see, correct or delete it sooner. Full notice: https://atombackends.com/privacy/\n\nOther ways in: MCP https://atombackends.com/mcp, A2A https://atombackends.com/.well-known/agent-card.json, guide https://atombackends.com/agents/.",
    "contact": {
      "name": "Atom Backends",
      "url": "https://atombackends.com/agents/",
      "email": "hello@atombackends.com"
    }
  },
  "servers": [
    {
      "url": "https://atombackends.com"
    }
  ],
  "paths": {
    "/api/agent-inquiry": {
      "post": {
        "operationId": "submitInquiry",
        "summary": "Send an inquiry to Atom Backends on behalf of a person",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Any unique string. A retry with the same key never records the inquiry twice."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "intent",
                  "need",
                  "contact",
                  "consent",
                  "on_behalf_of"
                ],
                "properties": {
                  "intent": {
                    "type": "string",
                    "enum": [
                      "request_quote",
                      "book_call",
                      "question",
                      "partnership",
                      "other"
                    ],
                    "description": "What the person wants: a quote, a call, an answer, a partnership, or other."
                  },
                  "need": {
                    "type": "string",
                    "minLength": 10,
                    "maxLength": 4000,
                    "description": "What the person needs, in their words: the problem, scope, roles or volumes."
                  },
                  "company": {
                    "type": "string",
                    "maxLength": 160,
                    "description": "The organization the person represents."
                  },
                  "contact": {
                    "type": "object",
                    "required": [
                      "name"
                    ],
                    "additionalProperties": false,
                    "description": "The person to answer. An email or a phone is required.",
                    "properties": {
                      "name": {
                        "type": "string",
                        "maxLength": 120
                      },
                      "role": {
                        "type": "string",
                        "maxLength": 160,
                        "description": "Job title or role."
                      },
                      "email": {
                        "type": "string",
                        "format": "email",
                        "maxLength": 200
                      },
                      "phone": {
                        "type": "string",
                        "maxLength": 32,
                        "description": "International format, e.g. +1 212 555 0100."
                      }
                    }
                  },
                  "budget": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Budget or range, free text (e.g. \"$20k-30k a month\")."
                  },
                  "timeline": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "When they want to start or decide."
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "en",
                      "es",
                      "pt"
                    ],
                    "description": "Language for the answer."
                  },
                  "consent": {
                    "type": "boolean",
                    "const": true,
                    "description": "True only if the person named in contact agreed to be contacted by this company about this inquiry."
                  },
                  "on_behalf_of": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "description": "Who the agent acts for: the person and, if any, their organization."
                  },
                  "agent": {
                    "type": "object",
                    "additionalProperties": false,
                    "description": "The agent sending this (optional but recommended). The User-Agent header is recorded too.",
                    "properties": {
                      "name": {
                        "type": "string",
                        "maxLength": 120
                      },
                      "url": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 300
                      },
                      "operator": {
                        "type": "string",
                        "maxLength": 160,
                        "description": "Who runs the agent."
                      }
                    }
                  },
                  "test": {
                    "type": "boolean",
                    "description": "True to test an integration: recorded and marked as a test, nobody follows up."
                  }
                }
              },
              "example": {
                "intent": "request_quote",
                "need": "Describe what the person needs, in their words.",
                "company": "Example Co",
                "contact": {
                  "name": "Sam Example",
                  "role": "VP Engineering",
                  "email": "sam@example.com"
                },
                "budget": "Optional",
                "timeline": "Optional",
                "language": "en",
                "consent": true,
                "on_behalf_of": "Sam Example, Example Co",
                "agent": {
                  "name": "Example assistant",
                  "operator": "Example AI"
                },
                "test": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Already received (same Idempotency-Key or same inquiry today).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "received",
                        "duplicate"
                      ]
                    },
                    "inquiry_id": {
                      "type": "string"
                    },
                    "brand": {
                      "type": "string"
                    },
                    "automated": {
                      "type": "boolean",
                      "const": true
                    },
                    "from": {
                      "type": "string"
                    },
                    "received_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "test": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "next_steps": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "action": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "minutes": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "reply_by": {
                      "type": "string",
                      "enum": [
                        "email",
                        "phone"
                      ]
                    },
                    "privacy": {
                      "type": "string"
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Received (automated acknowledgement).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "received",
                        "duplicate"
                      ]
                    },
                    "inquiry_id": {
                      "type": "string"
                    },
                    "brand": {
                      "type": "string"
                    },
                    "automated": {
                      "type": "boolean",
                      "const": true
                    },
                    "from": {
                      "type": "string"
                    },
                    "received_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "test": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "next_steps": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "action": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "minutes": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "reply_by": {
                      "type": "string",
                      "enum": [
                        "email",
                        "phone"
                      ]
                    },
                    "privacy": {
                      "type": "string"
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid inquiry: errors lists each field and the problem.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string"
                          },
                          "problem": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "retry_after_seconds": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "This brand takes no inquiries here.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string"
                          },
                          "problem": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "retry_after_seconds": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Body larger than 16384 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string"
                          },
                          "problem": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "retry_after_seconds": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Content-Type must be application/json.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string"
                          },
                          "problem": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "retry_after_seconds": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate or daily limit; see Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string"
                          },
                          "problem": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "retry_after_seconds": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Not confirmed; retry with the same Idempotency-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string"
                          },
                          "problem": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "retry_after_seconds": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}