{ "openapi": "3.1.0", "info": { "title": "Mayan Assistant HTTP API", "version": "1.0.0", "summary": "User-scoped draft proposals and setup guidance for vehicle records.", "description": "Mayan is a vehicle-management pilot. This custom HTTP API exposes three existing proposal/read tools. It is not an MCP server and no conversational AI or external OCR provider is connected. A verified user session and existing vehicle permissions are required for POST. Tools cannot approve or delete financial records, change access, execute SQL or fetch arbitrary URLs. Keep user credentials in a trusted adapter, never in model context. Users review and confirm financial records in the website.", "contact": { "url": "https://mayan-kalsuwaidan.vercel.app/contact" } }, "servers": [ { "url": "https://mayan-kalsuwaidan.vercel.app" } ], "externalDocs": { "description": "Mayan user guide, privacy boundaries and assistant integration.", "url": "https://mayan-kalsuwaidan.vercel.app/docs" }, "tags": [ { "name": "Assistant", "description": "Three provider-independent tools with existing user and vehicle permissions." } ], "paths": { "/api/assistant": { "get": { "operationId": "getAssistantManifest", "tags": [ "Assistant" ], "summary": "Read the public assistant manifest", "description": "Returns contract schemas and current capability flags. Contains no user context or credentials.", "security": [], "responses": { "200": { "description": "Public tool manifest.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manifest" } } } } } }, "post": { "operationId": "invokeAssistantTool", "tags": [ "Assistant" ], "summary": "Invoke one user-scoped proposal/read tool", "description": "Requires a verified email account and current vehicle access. Draft proposals additionally require owner or editor permission. Existing database row-level access controls remain authoritative; this endpoint grants no extra access. Browser requests must be same-origin; a trusted server adapter may call using the user session. Unknown/moved or archived vehicle records are not made public. No financial confirmation operation is exposed.", "security": [ { "UserBearer": [] } ], "x-request-body-max-bytes": 160000, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string", "const": "propose_entry_draft" }, "vehicle_id": { "type": "string", "format": "uuid", "description": "An active vehicle accessible to the authenticated user. It does not select another owner." }, "arguments": { "allOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "fuel", "service", "invoice" ] }, "text": { "type": "string", "maxLength": 12000 }, "payload": { "type": "object", "properties": { "record": { "type": "object", "properties": { "occurred_on": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "amount": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "odometer_km": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "invoice_id": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "fuel_type": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "liters": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "unit_price": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "station": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "is_full": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "gap_before": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "amount_basis": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "spend_category": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "workshop": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "parts": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "next_due_km": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "next_due_on": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "vendor": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "invoice_number": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "paid_amount": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "due_on": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, "invoice": { "anyOf": [ { "type": "object", "properties": { "occurred_on": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "amount": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "vendor": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "invoice_number": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "paid_amount": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] }, "due_on": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number", "minimum": 0, "maximum": 9999999999.99 }, { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": [ "kind" ], "additionalProperties": false }, { "anyOf": [ { "required": [ "payload" ] }, { "required": [ "text" ], "properties": { "text": { "type": "string", "pattern": "\\S" } } } ] } ] }, "language": { "type": "string", "enum": [ "ar", "en" ], "default": "en" } }, "required": [ "tool", "vehicle_id", "arguments" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string", "const": "list_my_drafts" }, "vehicle_id": { "type": "string", "format": "uuid", "description": "An active vehicle accessible to the authenticated user. It does not select another owner." }, "arguments": { "type": "object", "properties": {}, "additionalProperties": false }, "language": { "type": "string", "enum": [ "ar", "en" ], "default": "en" } }, "required": [ "tool", "vehicle_id" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string", "const": "get_setup_feedback" }, "vehicle_id": { "type": "string", "format": "uuid", "description": "An active vehicle accessible to the authenticated user. It does not select another owner." }, "arguments": { "type": "object", "properties": {}, "additionalProperties": false }, "language": { "type": "string", "enum": [ "ar", "en" ], "default": "en" } }, "required": [ "tool", "vehicle_id" ], "additionalProperties": false } ], "discriminator": { "propertyName": "tool" } } } } }, "responses": { "200": { "description": "Tool result within the authenticated user and vehicle scope. Financial confirmation remains a separate user action in the website.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResponse" } } } }, "400": { "description": "Malformed request or unsupported tool arguments.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A verified, non-anonymous user session is required.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The origin or the current user is not permitted to perform this action.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The vehicle is unavailable within the current user scope.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "This HTTP method is not supported.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The draft changed or conflicts with an existing draft.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request exceeds the 160,000-byte body limit.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Send the request as application/json.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed. Raw internal errors are not returned.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The integration is not configured for this deployment.", "headers": { "Cache-Control": { "description": "Private responses must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "UserBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Existing verified user access token. The token is verified server-side and requests remain scoped by that user’s database permissions. This is not an administrator credential, a new OAuth grant or an independently restricted bot token." } }, "schemas": { "Manifest": { "type": "object", "properties": { "version": { "type": "string", "const": "1.0.0" }, "tools": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "propose_entry_draft", "list_my_drafts", "get_setup_feedback" ] }, "description": { "type": "string" }, "input_schema": { "type": "object", "additionalProperties": true } }, "required": [ "name", "description", "input_schema" ], "additionalProperties": false } }, "provider_connected": { "type": "boolean", "const": false }, "review_required": { "type": "boolean", "const": true }, "document_processing": { "type": "string", "const": "local_text_and_ocr" }, "assistant_mode": { "type": "string", "const": "local_guided" } }, "required": [ "version", "tools", "provider_connected", "review_required", "document_processing", "assistant_mode" ], "additionalProperties": false }, "ToolResponse": { "type": "object", "properties": { "version": { "type": "string", "const": "1.0.0" }, "result": { "oneOf": [ { "$ref": "#/components/schemas/DraftProposalResult" }, { "$ref": "#/components/schemas/DraftListResult" }, { "$ref": "#/components/schemas/SetupFeedbackResult" } ] }, "review_required": { "type": "boolean", "const": true } }, "required": [ "version", "result", "review_required" ], "additionalProperties": false }, "DraftProposalResult": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "fuel", "service", "invoice" ] }, "status": { "type": "string", "const": "draft" }, "payload": { "type": "object", "description": "Normalized editable fields accepted by the selected tool. Drafts may be incomplete.", "additionalProperties": true } }, "required": [ "id", "kind", "status", "payload" ], "additionalProperties": false }, "proposal": { "type": "object", "description": "Editable fields, exact source evidence, missing fields and review warnings. Source text remains untrusted data.", "additionalProperties": true }, "requiresReview": { "type": "boolean", "const": true } }, "required": [ "draft", "proposal", "requiresReview" ], "additionalProperties": false }, "DraftListResult": { "type": "object", "properties": { "drafts": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "fuel", "service", "invoice" ] }, "status": { "type": "string", "const": "draft" }, "title": { "type": "string" }, "occurred_on": { "type": "string", "format": "date" }, "amount": { "type": [ "string", "number" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "status" ], "additionalProperties": false } }, "truncated": { "type": "boolean" } }, "required": [ "drafts", "truncated" ], "additionalProperties": false }, "SetupFeedbackResult": { "type": "object", "properties": { "goal": { "type": [ "string", "null" ], "enum": [ "reliability", "cost", "offroad", "restoration", null ] }, "feedback": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 3 }, "href": { "type": "string", "pattern": "^/(?!/)" } }, "required": [ "id", "title", "body", "priority" ], "additionalProperties": false } } }, "required": [ "goal", "feedback" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Safe human-readable description without raw internal error data." }, "hint": { "type": "string", "description": "Safe recovery guidance." }, "documentation_url": { "type": "string", "format": "uri", "const": "https://mayan-kalsuwaidan.vercel.app/docs" } }, "required": [ "error", "message", "hint", "documentation_url" ], "additionalProperties": false } } } }