{ "openapi": "3.1.0", "info": { "title": "CorporateSaathi Public Developer & AI Agent API", "version": "1.0.0", "description": "Official programmatic API specification for CorporateSaathi - India's premier digital platform for company incorporation, GST registration, trademark filings, and legal compliance. All endpoints use URL path versioning (/v1/) and return RFC 9457 typed error responses.", "contact": { "name": "CorporateSaathi Technical & Developer Support", "email": "support@corporatesaathi.com", "url": "https://corporatesaathi.com/developers" }, "license": { "name": "Proprietary / Open Developer Access", "url": "https://corporatesaathi.com/terms-and-conditions" }, "x-versioning-policy": { "strategy": "URL path versioning (/v1/) and optional API-Version request header", "current_version": "v1", "header": "API-Version: 1.0", "deprecation_policy_url": "https://corporatesaathi.com/developers/deprecation-policy" }, "x-deprecation-policy": { "notice_period_days": 180, "policy_url": "https://corporatesaathi.com/developers/deprecation-policy", "headers": { "deprecation": "RFC 8594 Deprecation header set to the date the endpoint is scheduled for removal", "sunset": "RFC 8594 Sunset header set to the final date of endpoint availability", "link": "RFC 8288 Link header pointing to successor endpoint documentation" }, "process": "1. Deprecation header added 180 days before removal. 2. Sunset header added with exact removal date. 3. Link header points to successor. 4. Endpoint returns HTTP 299 deprecation warning. 5. After Sunset date, endpoint returns 410 Gone." }, "x-cli-package": { "package": "@corporatesaathi/cli", "install": "npm install -g @corporatesaathi/cli", "npx": "npx corporatesaathi ", "pypi": "pip install corporatesaathi", "repository": "https://github.com/corporatesaathidb-arch/cli", "commands": [ "corporatesaathi services list", "corporatesaathi services search ", "corporatesaathi compliance calendar --type pvt_ltd", "corporatesaathi calculate cost --state Delhi --capital 100000", "corporatesaathi name check " ] } }, "servers": [ { "url": "https://corporatesaathi.com/api/v1", "description": "Production Versioned API Gateway (v1)" }, { "url": "https://corporatesaathi.com/api", "description": "Production Web API Gateway" } ], "paths": { "/services": { "get": { "summary": "List Available Legal & Compliance Services", "description": "Returns a structured catalog of business registration, GST, trademark, compliance, and legal packages with pricing in INR.", "operationId": "getServicesList", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Filter by category: registrations, tax, compliance, ip, advisory", "schema": { "type": "string", "enum": ["all", "registrations", "tax", "compliance", "ip", "advisory"] } }, { "name": "search", "in": "query", "required": false, "description": "Keyword search query (e.g. GST, Private Limited, Trademark)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful retrieval of service catalog", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicesListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/compliance-calendar": { "get": { "summary": "Get Mandatory Compliance Deadlines", "description": "Returns upcoming ROC, GST, TDS, and Advance Tax statutory deadlines for Indian business entities.", "operationId": "getComplianceCalendar", "parameters": [ { "name": "entityType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["pvt_ltd", "llp", "opc", "proprietorship", "partnership"], "default": "pvt_ltd" }, "description": "Indian business entity legal structure" } ], "responses": { "200": { "description": "Compliance schedule data", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceCalendarResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "429": { "$ref": "#/components/responses/RateLimitedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/mcp": { "get": { "summary": "MCP Server Metadata & Capability Handshake", "description": "Returns Model Context Protocol (MCP) server capabilities, tool list, and streamable transport endpoints for AI agent integration.", "operationId": "getMcpMetadata", "responses": { "200": { "description": "MCP server metadata and capability listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpMetadataResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "MCP JSON-RPC 2.0 Execution", "description": "Executes MCP JSON-RPC methods: initialize, tools/list, tools/call, resources/list, resources/read, ping.", "operationId": "executeMcpRpc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } }, "responses": { "200": { "description": "Successful JSON-RPC response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/health": { "get": { "summary": "API Health Check", "description": "Returns system status and API availability. Useful for monitoring and agent pre-flight checks.", "operationId": "getApiHealth", "responses": { "200": { "description": "API is operational", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckResponse" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "headers": { "RateLimit-Limit": { "schema": { "type": "integer", "example": 100 }, "description": "The maximum number of requests allowed in the current time window (RFC RateLimit)." }, "RateLimit-Remaining": { "schema": { "type": "integer", "example": 99 }, "description": "The number of remaining requests in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer", "example": 60 }, "description": "The number of seconds until the rate limit window resets." }, "Retry-After": { "schema": { "type": "integer", "example": 60 }, "description": "The number of seconds to wait before retrying after encountering a 429." }, "X-API-Version": { "schema": { "type": "string", "example": "1.0.0" }, "description": "The active version of the API." } }, "schemas": { "ServiceItem": { "type": "object", "required": ["id", "title", "slug", "price", "description", "category"], "properties": { "id": { "type": "string", "example": "gst-reg" }, "title": { "type": "string", "example": "GST Registration Online" }, "slug": { "type": "string", "example": "gst-registration" }, "price": { "type": "string", "example": "99" }, "description": { "type": "string", "example": "Online GST registration with complete document verification and ARN tracking." }, "category": { "type": "string", "example": "tax" } } }, "ServicesListResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "required": ["total", "services"], "properties": { "total": { "type": "integer", "example": 5 }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceItem" } } } } } }, "ComplianceDeadline": { "type": "object", "required": ["form", "dueDate", "description"], "properties": { "form": { "type": "string", "example": "GSTR-1 (Monthly)" }, "dueDate": { "type": "string", "example": "11th of every month" }, "description": { "type": "string", "example": "Outward supplies statement" } } }, "ComplianceCalendarResponse": { "type": "object", "required": ["status", "entityType", "deadlines"], "properties": { "status": { "type": "string", "example": "success" }, "entityType": { "type": "string", "example": "pvt_ltd" }, "deadlines": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceDeadline" } } } }, "McpMetadataResponse": { "type": "object", "required": ["protocolVersion", "serverInfo", "capabilities"], "properties": { "jsonrpc": { "type": "string", "example": "2.0" }, "protocolVersion": { "type": "string", "example": "2024-11-05" }, "serverInfo": { "type": "object", "properties": { "name": { "type": "string", "example": "corporatesaathi-mcp" }, "version": { "type": "string", "example": "1.0.0" }, "description": { "type": "string" }, "homepage": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" } } }, "capabilities": { "type": "object" }, "tools": { "type": "array", "items": { "type": "object" } } } }, "JsonRpcRequest": { "type": "object", "required": ["jsonrpc", "method"], "properties": { "jsonrpc": { "type": "string", "const": "2.0", "example": "2.0" }, "method": { "type": "string", "enum": ["initialize", "notifications/initialized", "ping", "tools/list", "tools/call", "resources/list", "resources/read"], "example": "tools/call" }, "id": { "type": ["string", "integer"], "example": 1 }, "params": { "type": "object", "example": { "name": "search_services", "arguments": { "query": "GST" } } } } }, "JsonRpcResponse": { "type": "object", "required": ["jsonrpc", "id"], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": ["string", "integer", "null"] }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object" } } } } }, "HealthCheckResponse": { "type": "object", "required": ["status", "version", "timestamp"], "properties": { "status": { "type": "string", "enum": ["healthy", "degraded"], "example": "healthy" }, "version": { "type": "string", "example": "1.0.0" }, "service": { "type": "string", "example": "CorporateSaathi Developer & Agent API" }, "timestamp": { "type": "string", "format": "date-time" }, "openapi": { "type": "string", "format": "uri" }, "mcp": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" } } }, "ErrorResponse": { "type": "object", "description": "Standard typed error object (RFC 9457 application/problem+json compliant) returned across all API endpoints.", "required": ["type", "title", "status", "detail", "error"], "properties": { "type": { "type": "string", "format": "uri", "example": "https://corporatesaathi.com/developers#errors", "description": "URI identifier specifying the error type" }, "title": { "type": "string", "example": "Resource Not Found", "description": "Short human-readable summary of the problem" }, "status": { "type": "integer", "example": 404, "description": "HTTP status code" }, "detail": { "type": "string", "example": "The requested API endpoint was not found.", "description": "Human-readable explanation specific to this occurrence of the problem" }, "error": { "type": "object", "required": ["code", "message", "status", "hint"], "properties": { "code": { "type": "string", "example": "RESOURCE_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "example": "The requested API endpoint was not found." }, "status": { "type": "integer", "example": 404 }, "hint": { "type": "string", "example": "Check available endpoints at https://corporatesaathi.com/openapi.json" }, "documentation_url": { "type": "string", "format": "uri", "example": "https://corporatesaathi.com/developers" } } } } } }, "responses": { "BadRequestError": { "description": "Bad Request - Invalid parameters or malformed payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundError": { "description": "Not Found - Requested API resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimitedError": { "description": "Too Many Requests - Rate limit exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }