{
  "openapi": "3.1.0",
  "info": {
    "title": "ZUMX agent hiring API",
    "version": "1.0.0",
    "summary": "Send Tahir Rasool (ZUMX) a project inquiry on behalf of a human client.",
    "description": "ZUMX is Tahir Rasool's independent digital build practice for small businesses: websites, custom web apps, and practical AI and automation. This API lets an AI agent send Tahir a project inquiry for its human client.\n\nRules:\n- Identify yourself as an AI assistant (agent_name) and name the client you act for (client_name).\n- Show the client the exact inquiry and get their explicit approval before sending. Set principal_approved to true only then; without it the request is rejected with 422.\n- An inquiry is a first message. It is not a booking, an accepted quote or a commitment. You cannot accept a quote, agree to scope, deadlines or contract terms, promise payment, or bind the client.\n- Never send passwords, payment details, private customer records or sensitive documents.\n- Include a budget or timeline only when the client explicitly authorised sharing it. ZUMX does not publish prices, delivery dates or availability.\n\nTahir replies to the client by email, and the client receives an automatic acknowledgement. If the API returns 502, email tahir@zumxlabs.xyz with the same approved message instead.",
    "contact": {
      "name": "Tahir Rasool",
      "email": "tahir@zumxlabs.xyz",
      "url": "https://zumxlabs.xyz/for-agents.html"
    }
  },
  "externalDocs": {
    "description": "For AI agents: rules and resources",
    "url": "https://zumxlabs.xyz/for-agents.html"
  },
  "servers": [
    {
      "url": "https://zumxlabs.xyz"
    }
  ],
  "tags": [
    {
      "name": "discovery"
    },
    {
      "name": "inquiries"
    }
  ],
  "paths": {
    "/api": {
      "get": {
        "tags": [
          "discovery"
        ],
        "operationId": "getApiIndex",
        "summary": "API index",
        "description": "What the API does, its endpoints, links to this document and the inquiry schema, and the rules an agent must follow.",
        "responses": {
          "200": {
            "description": "The index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "service": "ZUMX agent hiring API",
                  "openapi": "https://zumxlabs.xyz/openapi.json",
                  "endpoints": [
                    {
                      "method": "GET",
                      "path": "/api"
                    },
                    {
                      "method": "GET",
                      "path": "/api/services"
                    },
                    {
                      "method": "POST",
                      "path": "/api/inquiries"
                    }
                  ],
                  "fallback_contact": "tahir@zumxlabs.xyz"
                }
              }
            }
          },
          "405": {
            "description": "Wrong method.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Use GET on this endpoint.",
                    "details": {
                      "allowed": [
                        "GET"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/services": {
      "get": {
        "tags": [
          "discovery"
        ],
        "operationId": "listServices",
        "summary": "Services and project types",
        "description": "The two service areas, the accepted project_type values, the process, and the commercial statement (no prices, availability or delivery dates are published). Read from the canonical agent profile.",
        "responses": {
          "200": {
            "description": "Services.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "operator": "ZUMX",
                  "principal": "Tahir Rasool",
                  "services": [
                    {
                      "id": "websites-web-apps",
                      "title": "Websites and web apps",
                      "url": "https://zumxlabs.xyz/services.html#websites"
                    },
                    {
                      "id": "ai-automation",
                      "title": "Practical AI and automation",
                      "url": "https://zumxlabs.xyz/services.html#ai"
                    }
                  ],
                  "project_types": [
                    "website",
                    "web app",
                    "AI or automation",
                    "not sure",
                    "other"
                  ],
                  "commercial": {
                    "pricing_published": false,
                    "availability_published": false
                  },
                  "inquiry_endpoint": "https://zumxlabs.xyz/api/inquiries"
                }
              }
            }
          },
          "405": {
            "description": "Wrong method.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Use GET on this endpoint.",
                    "details": {
                      "allowed": [
                        "GET"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/inquiries": {
      "post": {
        "tags": [
          "inquiries"
        ],
        "operationId": "createInquiry",
        "summary": "Send a project inquiry for a human client",
        "description": "Validates the JSON body against https://zumxlabs.xyz/schemas/project-inquiry.schema.json (unknown fields are rejected; body at most 20 KB) and delivers it to Tahir. Requires principal_approved: true.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "https://zumxlabs.xyz/schemas/project-inquiry.schema.json"
              },
              "examples": {
                "website": {
                  "summary": "A first website for a small business",
                  "value": {
                    "client_name": "Ayesha Khan",
                    "client_email": "ayesha@example.com",
                    "project_type": "website",
                    "message": "A first website for a small bakery: menu, opening hours and an enquiry form for custom cake orders. We currently take orders through Instagram messages.",
                    "agent_name": "Example Assistant",
                    "agent": "ExampleCorp assistant v2",
                    "principal_approved": true,
                    "company": "Khan Bakery",
                    "links": [
                      "https://example.com/khan-bakery"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Received and delivered to Tahir. Nothing has been booked, quoted or agreed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InquiryReceived"
                },
                "example": {
                  "status": "received",
                  "inquiry_id": "6f1c2a7e-3b9d-4e0a-9c55-1d2e3f4a5b6c",
                  "submitted_at": "2026-10-15T12:00:00.000Z",
                  "message": "Tahir will reply to the client's email shortly",
                  "next_steps": [
                    "Tahir Rasool reads the inquiry and replies to ayesha@example.com directly.",
                    "An automatic acknowledgement email is sent to that address.",
                    "Nothing has been booked, quoted or agreed. Scope and a written quote are discussed with the client before any build.",
                    "Keep inquiry_id for reference. For anything else, the client can email tahir@zumxlabs.xyz."
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Empty body or invalid JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_json",
                    "message": "The request body is not valid JSON.",
                    "details": null
                  }
                }
              }
            }
          },
          "405": {
            "description": "Wrong method.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Use POST on this endpoint.",
                    "details": {
                      "allowed": [
                        "POST"
                      ]
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Body larger than 20 KB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "payload_too_large",
                    "message": "The request body must be at most 20480 bytes.",
                    "details": {
                      "max_bytes": 20480
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Body is not JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unsupported_media_type",
                    "message": "Send the inquiry as JSON with Content-Type: application/json.",
                    "details": {
                      "expected": "application/json",
                      "received": "text/plain"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation failed, or principal_approved is missing or not true.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "principal_approval_required": {
                    "value": {
                      "error": {
                        "code": "principal_approval_required",
                        "message": "principal_approved must be true. Show the exact inquiry to your human client, get their explicit approval to send it, then set principal_approved to true. Do not send it otherwise.",
                        "details": [
                          {
                            "field": "principal_approved",
                            "issue": "required",
                            "message": "is required"
                          }
                        ]
                      }
                    }
                  },
                  "validation_failed": {
                    "value": {
                      "error": {
                        "code": "validation_failed",
                        "message": "The inquiry does not match the schema. See details for each field.",
                        "details": [
                          {
                            "field": "client_email",
                            "issue": "format",
                            "message": "must be a valid email address"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many inquiries from one address in a short time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many inquiries from this address. Wait a minute and try again, or email tahir@zumxlabs.xyz.",
                    "details": null
                  }
                }
              }
            }
          },
          "502": {
            "description": "The inquiry could not be delivered. Email tahir@zumxlabs.xyz instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "upstream_failed",
                    "message": "The inquiry could not be delivered.",
                    "details": {
                      "upstream_status": 500,
                      "fallback": {
                        "email": "tahir@zumxlabs.xyz",
                        "instructions": "The inquiry was not delivered. Email the same approved message to tahir@zumxlabs.xyz instead, with the client's name and reply address, or try again later."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "details"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "empty_body",
                  "invalid_json",
                  "method_not_allowed",
                  "not_found",
                  "payload_too_large",
                  "unsupported_media_type",
                  "validation_failed",
                  "principal_approval_required",
                  "rate_limited",
                  "upstream_failed",
                  "upstream_unavailable",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              },
              "details": {}
            }
          }
        }
      },
      "InquiryReceived": {
        "type": "object",
        "required": [
          "status",
          "inquiry_id",
          "message",
          "next_steps"
        ],
        "properties": {
          "status": {
            "const": "received"
          },
          "inquiry_id": {
            "type": "string",
            "format": "uuid"
          },
          "submitted_at": {
            "type": "string",
            "format": "date-time"
          },
          "message": {
            "type": "string"
          },
          "next_steps": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}