{
  "openapi": "3.1.0",
  "info": {
    "title": "Nirmatas Global 3D Printing & Manufacturing API",
    "description": "Official REST API and agentic tool contract for Nirmatas (https://www.nirmatas.com) — the global peer-to-peer on-demand 3D printing and additive manufacturing marketplace. Enables AI agents and developers to search live manufacturing jobs, inspect engineering tolerances, calculate instant quotes, and integrate custom fabrication pipelines.\n\n### REST API Versioning Policy\n- **Active LTS Version**: `v1.0.0` (Signaled via version parameter header `X-API-Version: 1.0.0`).\n- **Deprecation Lifecycle**: Deprecated endpoints are supported for at least 12 months, signaled via `Deprecation` and `Sunset` HTTP response headers.\n- **Error Specification**: RFC 9457 structured `application/problem+json` standard with actionable resolution hints.\n- **Rate Limits**: 100 requests per 60 seconds with IETF `RateLimit-*` headers.",
    "version": "1.0.0",
    "contact": {
      "name": "Nirmatas Developer Support",
      "email": "support@nirmatas.com",
      "url": "https://www.nirmatas.com/developers"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.nirmatas.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.nirmatas.com",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/jobs": {
      "get": {
        "summary": "Search 3D printing jobs and parts",
        "description": "Search active 3D printing requirements, custom parts, and print farm capacity across the global marketplace.",
        "operationId": "searchMarketplaceJobs",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "Keyword search query (e.g. 'TPU GoPro mount', 'drone arm', 'resin prototype')",
            "required": false,
            "schema": {
              "type": "string",
              "example": "TPU drone mount"
            }
          },
          {
            "name": "material",
            "in": "query",
            "description": "Filter by additive manufacturing material polymer or resin",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["TPU_95A", "PETG_CF", "SLA_Resin", "PLA", "ABS", "Nylon_PA12"],
              "example": "TPU_95A"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter by listing type: 'job' (custom requirement) or 'part' (ready-to-buy part)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["all", "job", "part"],
              "default": "all"
            }
          },
          {
            "name": "X-API-Version",
            "in": "header",
            "description": "API Versioning header",
            "required": false,
            "schema": {
              "type": "string",
              "default": "1.0.0"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful search results with matching listings",
            "headers": {
              "RateLimit-Limit": { "schema": { "type": "integer", "example": 100 } },
              "RateLimit-Remaining": { "schema": { "type": "integer", "example": 99 } },
              "RateLimit-Reset": { "schema": { "type": "integer", "example": 60 } },
              "X-API-Version": { "schema": { "type": "string", "example": "1.0.0" } },
              "Vary": { "schema": { "type": "string", "example": "Accept, Accept-Encoding" } }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketplaceSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a new 3D printing requirement",
        "description": "Post custom CAD design geometry requirements for quoting by verified farm operators.",
        "operationId": "createJobRequirement",
        "parameters": [
          {
            "name": "X-API-Version",
            "in": "header",
            "schema": { "type": "string", "default": "1.0.0" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateJobRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Job requirement created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobItem"
                }
              }
            }
          }
        }
      }
    },
    "/api/materials": {
      "get": {
        "summary": "List all supported 3D printing materials",
        "description": "Retrieve comprehensive list of supported polymers, composites, and photopolymer resins.",
        "operationId": "listMaterials",
        "parameters": [
          {
            "name": "X-API-Version",
            "in": "header",
            "schema": { "type": "string", "default": "1.0.0" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of supported materials",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "materials": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MaterialSpecification"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/materials/{slug}": {
      "get": {
        "summary": "Get material technical specifications",
        "description": "Retrieve detailed mechanical properties, tolerances, HDT, infill guidelines, and suitable applications for a specific material.",
        "operationId": "getMaterialSpecification",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The URL slug identifier of the material",
            "schema": {
              "type": "string",
              "enum": [
                "tpu-95a-3d-printing",
                "carbon-fiber-petg-3d-printing",
                "resin-sla-3d-printing",
                "pla-petg-abs-fdm-3d-printing"
              ],
              "example": "tpu-95a-3d-printing"
            }
          },
          {
            "name": "X-API-Version",
            "in": "header",
            "schema": { "type": "string", "default": "1.0.0" }
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed material specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MaterialSpecification"
                }
              }
            }
          },
          "404": {
            "description": "Material not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/quotes": {
      "post": {
        "summary": "Estimate manufacturing quote",
        "description": "Calculates instant pricing estimates and turnaround times based on polymer selection, part weight, and volume.",
        "operationId": "calculateQuoteEstimate",
        "parameters": [
          {
            "name": "X-API-Version",
            "in": "header",
            "schema": { "type": "string", "default": "1.0.0" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["material", "grams"],
                "properties": {
                  "material": { "type": "string", "example": "TPU_95A" },
                  "grams": { "type": "number", "example": 85 },
                  "quantity": { "type": "integer", "default": 1, "example": 5 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Estimated cost quote",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteEstimateResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/farms": {
      "get": {
        "summary": "List regional print farm hubs",
        "description": "Retrieve verified additive manufacturing hubs across North America, Europe, Australia, and Asia.",
        "operationId": "listRegionalFarms",
        "parameters": [
          {
            "name": "X-API-Version",
            "in": "header",
            "schema": { "type": "string", "default": "1.0.0" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of regional hubs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "hubs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FarmHub"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/tickets": {
      "get": {
        "summary": "Get support tickets",
        "description": "Retrieve customer support tickets and status.",
        "operationId": "getSupportTickets",
        "parameters": [
          {
            "name": "X-API-Version",
            "in": "header",
            "schema": { "type": "string", "default": "1.0.0" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of support tickets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/TicketItem" } }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Submit a support ticket or inquiry",
        "description": "Log an inquiry directly with the Nirmatas engineering and support team.",
        "operationId": "createSupportTicket",
        "parameters": [
          {
            "name": "X-API-Version",
            "in": "header",
            "schema": { "type": "string", "default": "1.0.0" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "message"],
                "properties": {
                  "name": { "type": "string", "example": "Jane Doe" },
                  "email": { "type": "string", "format": "email", "example": "jane@example.com" },
                  "subject": { "type": "string", "example": "Custom TPU Batch Requirement" },
                  "message": { "type": "string", "example": "We require 200 units of TPU 95A quad mounts." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ticket submitted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "contact_reference": { "type": "string", "example": "NIRM-K8DJF9" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/sandbox": {
      "get": {
        "summary": "Sandbox testing environment",
        "description": "Returns mock listings, quote calculations, and system status for AI agent testing.",
        "operationId": "getSandboxData",
        "parameters": [
          {
            "name": "X-API-Version",
            "in": "header",
            "schema": { "type": "string", "default": "1.0.0" }
          }
        ],
        "responses": {
          "200": {
            "description": "Mock sandbox data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "sandbox_active" },
                    "version": { "type": "string", "example": "1.0.0" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "required": ["type", "title", "status", "detail"],
        "properties": {
          "type": { "type": "string", "format": "uri", "example": "https://nirmatas.com/errors/invalid-parameters" },
          "title": { "type": "string", "example": "Invalid Parameters" },
          "status": { "type": "integer", "example": 400 },
          "code": { "type": "string", "example": "invalid_parameters" },
          "detail": { "type": "string", "example": "The parameter specified is invalid." },
          "resolution": { "type": "string", "example": "Consult documentation at https://www.nirmatas.com/developers." }
        }
      },
      "MarketplaceSearchResponse": {
        "type": "object",
        "required": ["status", "count", "listings"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "count": { "type": "integer", "example": 12 },
          "listings": { "type": "array", "items": { "$ref": "#/components/schemas/ListingItem" } }
        }
      },
      "ListingItem": {
        "type": "object",
        "required": ["id", "title", "type", "material", "created_at"],
        "properties": {
          "id": { "type": "string", "example": "4a2b1c8e-3d5f-4a9b-8c7d-1e2f3a4b5c6d" },
          "title": { "type": "string", "example": "GoPro Hero 12 TPU 95A Quad Mount" },
          "type": { "type": "string", "enum": ["job", "part"], "example": "part" },
          "material": { "type": "string", "example": "TPU_95A" },
          "price_usd": { "type": "number", "example": 4.5 },
          "price_inr": { "type": "number", "example": 350 },
          "url": { "type": "string", "format": "uri", "example": "https://www.nirmatas.com/jobs" }
        }
      },
      "CreateJobRequest": {
        "type": "object",
        "required": ["title", "material", "quantity"],
        "properties": {
          "title": { "type": "string", "example": "Custom FPV Drone Frame" },
          "material": { "type": "string", "example": "Carbon_Fiber_PETG" },
          "quantity": { "type": "integer", "example": 10 },
          "description": { "type": "string", "example": "High rigidity drone arms." }
        }
      },
      "JobItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "job_92kd84h" },
          "title": { "type": "string", "example": "Custom FPV Drone Frame" },
          "status": { "type": "string", "example": "open" }
        }
      },
      "MaterialSpecification": {
        "type": "object",
        "required": ["name", "category", "hardness_or_modulus", "heat_deflection_temp", "primary_use_cases"],
        "properties": {
          "name": { "type": "string", "example": "TPU 95A (Thermoplastic Polyurethane)" },
          "category": { "type": "string", "example": "Flexible Elastomer" },
          "hardness_or_modulus": { "type": "string", "example": "95 Shore A, >450% Elongation at Break" },
          "heat_deflection_temp": { "type": "string", "example": "60°C" },
          "recommended_tolerances": { "type": "string", "example": "±0.20mm" },
          "primary_use_cases": { "type": "array", "items": { "type": "string" }, "example": ["FPV drone camera mounts", "Gaskets", "Bumpers"] }
        }
      },
      "QuoteEstimateResponse": {
        "type": "object",
        "properties": {
          "material": { "type": "string", "example": "TPU_95A" },
          "grams": { "type": "number", "example": 85 },
          "quantity": { "type": "integer", "example": 5 },
          "estimated_cost_usd": { "type": "number", "example": 22.5 },
          "estimated_cost_inr": { "type": "number", "example": 1850 },
          "turnaround_hours": { "type": "string", "example": "24–48 Hours" }
        }
      },
      "FarmHub": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "example": "United States Hub" },
          "code": { "type": "string", "example": "US" },
          "capabilities": { "type": "array", "items": { "type": "string" }, "example": ["FDM", "SLA", "TPU", "CF-PETG"] }
        }
      },
      "TicketItem": {
        "type": "object",
        "properties": {
          "ticket_ref": { "type": "string", "example": "NIRM-MT4FUPJT" },
          "name": { "type": "string", "example": "Jane Doe" },
          "status": { "type": "string", "example": "open" }
        }
      }
    }
  }
}