{"openapi":"3.1.0","info":{"title":"Omnifex Public API & Agent Interfaces","description":"Production-grade, machine-accessible API and Model Context Protocol (MCP) server for Omnifex Technologies — custom software engineering, intelligent workflow automation, and applied AI research.","version":"1.0.0","contact":{"name":"Omnifex Engineering Intake","email":"contact@omnifex.in","url":"https://omnifex.in"},"license":{"name":"Proprietary / Open Agent Access","url":"https://omnifex.in/docs"},"x-api-versioning":{"strategy":"url-path-and-header","currentVersion":"1.0.0","headerName":"X-API-Version","pathPrefix":"/api/v1","description":"All endpoints support URL path versioning (/api/v1/...) and header versioning via X-API-Version. Unversioned endpoints route to current stable v1."},"x-deprecation-policy":{"noticePeriodDays":180,"sunsetHeader":"Sunset","deprecationHeader":"Deprecation","timeline":"Breaking changes will be preceded by a minimum 6-month deprecation period signaled via standard IETF Deprecation and Sunset response headers.","policyUrl":"https://omnifex.in/docs#versioning-and-deprecation"}},"servers":[{"url":"https://omnifex.in/api/v1","description":"V1 Path-Versioned API Server"},{"url":"https://omnifex.in","description":"Canonical Production Server"}],"components":{"headers":{"RateLimit-Limit":{"description":"The maximum number of requests allowed in the current rate limit window.","schema":{"type":"integer","example":100}},"RateLimit-Remaining":{"description":"The number of remaining requests allowed in the current rate limit window.","schema":{"type":"integer","example":99}},"RateLimit-Reset":{"description":"The number of seconds remaining until the rate limit window resets.","schema":{"type":"integer","example":60}},"RateLimit-Policy":{"description":"The quota policy applicable to the requesting client.","schema":{"type":"string","example":"\"100;w=60\""}},"Retry-After":{"description":"Seconds to wait before retrying when throttled (HTTP 429).","schema":{"type":"integer","example":60}},"X-API-Version":{"description":"The active semantic version of the Omnifex API serving the response.","schema":{"type":"string","example":"1.0.0"}}},"schemas":{"ErrorDetail":{"type":"object","description":"RFC 9457 structured error details with machine-readable code and agent resolution hint.","required":["code","message","resolution"],"properties":{"code":{"type":"string","description":"Machine-readable uppercase error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human- and agent-readable explanation of the error","example":"Problem description must be at least 10 characters."},"resolution":{"type":"string","description":"Concrete instructions for the agent or developer to resolve the failure","example":"Provide a summary of what technical challenge or project scope needs to be addressed."},"details":{"type":["object","null"],"description":"Supplemental validation details, field markers, or diagnostic telemetry","nullable":true},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the error occurred","example":"2026-10-25T13:30:00.000Z"},"status":{"type":"integer","description":"HTTP status code matching response","example":422}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"EnquiryInput":{"type":"object","required":["name","email","intent","problem"],"properties":{"name":{"type":"string","minLength":2,"description":"Contact name or autonomous agent identifier","example":"Research Agent / Jane Doe"},"email":{"type":"string","format":"email","description":"Contact email for proposal or technical follow-up","example":"contact@partner.org"},"intent":{"type":"string","enum":["software","ai","research","automation","existing","unsure","general","Custom Software","Intelligent Automation","Applied AI Research"],"description":"Primary discipline or domain of interest","example":"software"},"problem":{"type":"string","minLength":10,"maxLength":5000,"description":"Detailed challenge description, technical constraints, or scope requirements","example":"We need an automated document reconciliation pipeline with human approval gates."},"organization":{"type":"string","description":"Company, university, or institution name","example":"Acme Logistics"},"timeline":{"type":"string","description":"Target deployment or milestone timeframe","example":"Q2 2027"},"budget":{"type":"string","description":"Estimated budget allocation","example":"$25,000 - $50,000"},"dataAvailability":{"type":"string","description":"Status of existing datasets, APIs, or schemas","example":"PostgreSQL database and OpenAPI 3.0 spec available"},"additionalNotes":{"type":"string","description":"Any extra architectural considerations or NDAs needed"}}},"EnquirySuccessResponse":{"type":"object","required":["success","enquiryId","message","receivedAt","sla"],"properties":{"success":{"type":"boolean","example":true},"enquiryId":{"type":"string","description":"Unique persistent tracking identifier for the inquiry","example":"ENQ-1774390000000-AB12C"},"message":{"type":"string","example":"Your enquiry has been securely received. An engineer will review your requirements and follow up within 1-2 business days."},"receivedAt":{"type":"string","format":"date-time"},"sla":{"type":"string","example":"Review within 1-2 business days"}}},"EnquiryMetadataResponse":{"type":"object","required":["endpoint","version","method","requiredFields","validIntents"],"properties":{"endpoint":{"type":"string","example":"/api/enquiries"},"version":{"type":"string","example":"1.0.0"},"method":{"type":"string","example":"POST"},"description":{"type":"string"},"requiredFields":{"type":"array","items":{"type":"string"},"example":["name","email","intent","problem"]},"optionalFields":{"type":"array","items":{"type":"string"}},"validIntents":{"type":"array","items":{"type":"string"}},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"windowMinutes":{"type":"integer"}}},"documentationUrl":{"type":"string","format":"uri"}}},"SandboxInput":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["ping","validate_inquiry","inspect_capabilities"],"description":"Sandbox test action to execute","example":"ping"},"payload":{"type":"object","description":"Optional payload payload when testing validation or tool execution"}}},"SandboxPingResponse":{"type":"object","required":["status","action","timestamp","sandbox","latencyMs"],"properties":{"status":{"type":"string","example":"success"},"action":{"type":"string","example":"ping"},"timestamp":{"type":"string","format":"date-time"},"sandbox":{"type":"boolean","example":true},"latencyMs":{"type":"number","example":1.2}}},"SandboxMetadataResponse":{"type":"object","required":["status","environment","message","availableActions"],"properties":{"status":{"type":"string","example":"active"},"environment":{"type":"string","example":"sandbox"},"message":{"type":"string"},"availableActions":{"type":"array","items":{"type":"string"},"example":["ping","validate_inquiry","inspect_capabilities"]}}},"McpResource":{"type":"object","required":["uri","name","description","mimeType"],"properties":{"uri":{"type":"string","example":"omnifex://company/profile"},"name":{"type":"string","example":"Omnifex Company Profile & Operating Model"},"description":{"type":"string"},"mimeType":{"type":"string","example":"application/json"}}},"McpTool":{"type":"object","required":["name","description","inputSchema"],"properties":{"name":{"type":"string","example":"omnifex_list_capabilities"},"description":{"type":"string"},"inputSchema":{"type":"object"}}},"McpDescriptorResponse":{"type":"object","required":["name","version","protocolVersion","transport","capabilities","tools","resources"],"properties":{"name":{"type":"string","example":"omnifex-mcp-server"},"version":{"type":"string","example":"1.0.0"},"protocolVersion":{"type":"string","example":"2024-11-05"},"transport":{"type":"string","example":"streamable-http"},"endpoint":{"type":"string","format":"uri"},"description":{"type":"string"},"capabilities":{"type":"object","properties":{"tools":{"type":"object"},"resources":{"type":"object"},"prompts":{"type":"object"}}},"serverInfo":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}},"tools":{"type":"array","items":{"$ref":"#/components/schemas/McpTool"}},"resources":{"type":"array","items":{"$ref":"#/components/schemas/McpResource"}}}},"McpRpcRequest":{"type":"object","required":["jsonrpc","id","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":["string","number"],"example":1},"method":{"type":"string","enum":["initialize","tools/list","tools/call","resources/list","resources/read","ping"],"example":"tools/list"},"params":{"type":"object"}}},"McpRpcResponse":{"type":"object","required":["jsonrpc","id"],"properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":["string","number","null"]},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}},"responses":{"BadRequestError":{"description":"RFC 9457 structured error response for invalid JSON or malformed syntax.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnprocessableEntityError":{"description":"RFC 9457 structured validation error indicating missing or invalid parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFoundError":{"description":"RFC 9457 structured error indicating resource or endpoint not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimitError":{"description":"RFC 9457 structured error indicating rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"RFC 9457 structured error for internal server errors.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/enquiries":{"post":{"summary":"Submit Project or Research Inquiry (Canonical)","description":"Machine-accessible endpoint for AI agents, partners, and clients to register a structured project inquiry.","operationId":"submitInquiry","parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"API version string (e.g. '1.0.0'). Defaults to 1.0.0.","schema":{"type":"string","default":"1.0.0"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnquiryInput"}}}},"responses":{"200":{"description":"Inquiry successfully accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnquirySuccessResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"422":{"$ref":"#/components/responses/UnprocessableEntityError"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"get":{"summary":"Get Enquiry API Metadata and Schema Requirements","description":"Returns field requirements, validation constraints, and supported intent categories for the inquiries API.","operationId":"getEnquiryMetadata","responses":{"200":{"description":"Endpoint schema metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnquiryMetadataResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/api/v1/enquiries":{"post":{"summary":"Submit Project or Research Inquiry (V1 Path-Versioned)","description":"Version 1 explicit path for AI agents, partners, and clients to submit structured engineering inquiries.","operationId":"submitInquiryV1","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnquiryInput"}}}},"responses":{"200":{"description":"Inquiry successfully accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnquirySuccessResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"422":{"$ref":"#/components/responses/UnprocessableEntityError"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"get":{"summary":"Get V1 Enquiry API Metadata","description":"Returns schema metadata and field rules for v1 inquiries.","operationId":"getEnquiryMetadataV1","responses":{"200":{"description":"Endpoint schema metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnquiryMetadataResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/mcp":{"post":{"summary":"Model Context Protocol (MCP) Streamable HTTP Transport","description":"Executes JSON-RPC 2.0 MCP protocol requests including tools/list, tools/call, resources/list, resources/read, and ping.","operationId":"executeMcpRpc","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpRpcRequest"}}}},"responses":{"200":{"description":"MCP JSON-RPC 2.0 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpRpcResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}}},"get":{"summary":"MCP Server Capability Descriptor or SSE Stream","description":"Returns the complete MCP capabilities descriptor JSON (tools and resources), or initiates an SSE stream when Accept: text/event-stream is sent.","operationId":"getMcpDescriptor","responses":{"200":{"description":"MCP Server descriptor or event-stream initialization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpDescriptorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/api/v1/mcp":{"post":{"summary":"MCP Streamable HTTP Transport (V1 Path-Versioned)","description":"Path-versioned V1 endpoint for MCP JSON-RPC 2.0 requests.","operationId":"executeMcpRpcV1","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpRpcRequest"}}}},"responses":{"200":{"description":"MCP JSON-RPC 2.0 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpRpcResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}}},"get":{"summary":"Get MCP Descriptor (V1 Path-Versioned)","description":"Returns MCP capabilities descriptor for v1.","operationId":"getMcpDescriptorV1","responses":{"200":{"description":"MCP Server descriptor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpDescriptorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/api/sandbox":{"post":{"summary":"Execute Sandbox Test Action","description":"Zero-friction sandbox allowing agents and developers to test schema validation and tool invocations without an API key.","operationId":"executeSandboxAction","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxInput"}}}},"responses":{"200":{"description":"Sandbox execution output","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxPingResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"422":{"$ref":"#/components/responses/UnprocessableEntityError"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"get":{"summary":"Get Sandbox Status and Available Actions","description":"Returns available testing actions and environment metadata.","operationId":"getSandboxMetadata","responses":{"200":{"description":"Sandbox metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxMetadataResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/api/v1/sandbox":{"post":{"summary":"Execute Sandbox Test Action (V1 Path-Versioned)","description":"Version 1 explicit path for sandbox validation.","operationId":"executeSandboxActionV1","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxInput"}}}},"responses":{"200":{"description":"Sandbox execution output","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxPingResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"422":{"$ref":"#/components/responses/UnprocessableEntityError"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"get":{"summary":"Get V1 Sandbox Status and Actions","description":"Returns available testing actions for v1.","operationId":"getSandboxMetadataV1","responses":{"200":{"description":"Sandbox metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxMetadataResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitError"}}}}}}