{ "openapi": "3.1.0", "info": { "title": "Mutamad Public API", "version": "1.0.0", "summary": "Public catalog, free sandbox, and contact API for Mutamad (معتمد).", "description": "Mutamad is a construction management system operated by Mutamad LLC. This specification describes the public agent API on https://mutamad.net. Use it to read the product catalog, issue a free sandbox key, read invented fixtures, or submit a contact request. Do not use it to read or change a customer project, or to approve, certify, or pay. Reads listed as zero-auth succeed without a token. Write echoes require the sandbox:write scope. Named OAuth scopes are least-privilege labels for the public sandbox issuer. They are not tenant permissions.", "contact": { "name": "Mutamad", "email": "contact@mutamad.net", "url": "https://mutamad.net/developers" }, "license": { "name": "Proprietary", "url": "https://mutamad.net/ai.txt" } }, "externalDocs": { "description": "Mutamad developer portal", "url": "https://mutamad.net/developers" }, "servers": [ { "url": "https://mutamad.net", "description": "Mutamad public site" } ], "tags": [ { "name": "Discovery", "description": "Find operations, docs, and health." }, { "name": "Catalog", "description": "Public product description. Zero-auth." }, { "name": "Sandbox", "description": "Free invented fixtures and self-serve keys. Not customer data." }, { "name": "Auth", "description": "Public sandbox client-credentials tokens." }, { "name": "Contact", "description": "Project proposal and agent registration." } ], "paths": { "/api": { "get": { "operationId": "getApiIndex", "summary": "List the public Mutamad API entry points", "description": "Returns the OpenAPI URL, developer portal, MCP endpoint, and zero-auth operations. No token is required.", "tags": [ "Discovery" ], "security": [ {}, { "mutamadOAuth": [ "content:read" ] } ], "responses": { "200": { "description": "API index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } } }, "405": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1": { "get": { "operationId": "getApiV1Index", "summary": "Describe Mutamad public API version 1", "description": "Returns version, tier, and the operations an agent can call without contacting sales.", "tags": [ "Discovery" ], "security": [ {}, { "mutamadOAuth": [ "content:read" ] } ], "responses": { "200": { "description": "Version index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiVersion" } } } }, "405": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/health": { "get": { "operationId": "getHealth", "summary": "Check the public API", "description": "Liveness of the public Mutamad API. Zero-auth. Does not report customer-tenant status.", "tags": [ "Discovery" ], "security": [ {}, { "mutamadOAuth": [ "content:read" ] } ], "responses": { "200": { "description": "Health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "405": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/catalog": { "get": { "operationId": "getCatalog", "summary": "Read the Mutamad product catalog", "description": "Returns what Mutamad is for, when an agent should use it, and what this public API cannot do. Zero-auth.", "tags": [ "Catalog" ], "security": [ {}, { "mutamadOAuth": [ "content:read" ] } ], "responses": { "200": { "description": "Product catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } }, "405": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/docs": { "get": { "operationId": "getDocsIndex", "summary": "List Mutamad developer resources", "description": "Returns predictable URLs for the developer portal, OpenAPI spec, llms.txt, auth.md, MCP manifest, and CLI. Zero-auth.", "tags": [ "Catalog" ], "security": [ {}, { "mutamadOAuth": [ "content:read" ] } ], "responses": { "200": { "description": "Documentation index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocsIndex" } } } }, "405": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/sandbox/projects": { "get": { "operationId": "listSandboxProjects", "summary": "List invented sandbox projects", "description": "Returns public sandbox fixtures. These are not customer projects. Zero-auth; a sandbox:read token is also accepted.", "tags": [ "Sandbox" ], "security": [ {}, { "mutamadOAuth": [ "sandbox:read" ] } ], "responses": { "200": { "description": "Sandbox projects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxProjectList" } } } }, "401": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/sandbox/projects/{projectId}": { "get": { "operationId": "getSandboxProject", "summary": "Read one invented sandbox project", "description": "Returns one sandbox fixture by id, including sample submittal and inspection records. Zero-auth.", "tags": [ "Sandbox" ], "security": [ {}, { "mutamadOAuth": [ "sandbox:read" ] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Sandbox project id, for example sbx-villa-014.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]+$", "examples": [ "sbx-villa-014" ] } } ], "responses": { "200": { "description": "Sandbox project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxProject" } } } }, "404": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/sandbox/records": { "post": { "operationId": "createSandboxRecord", "summary": "Echo an ephemeral sandbox record", "description": "Requires a sandbox:write bearer token from the free self-serve key endpoint. The response is not stored and cannot affect a customer project.", "tags": [ "Sandbox" ], "security": [ { "mutamadOAuth": [ "sandbox:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxRecordRequest" } } } }, "responses": { "201": { "description": "Ephemeral sandbox record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxRecordEcho" } } } }, "400": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/sandbox/keys": { "post": { "operationId": "createSandboxKey", "summary": "Issue a free sandbox API key", "description": "Self-serve. No account, payment, or sales form. Returns a bearer token for the requested public scopes. The token cannot access customer projects.", "tags": [ "Sandbox" ], "security": [ {} ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxKeyRequest" } } } }, "responses": { "201": { "description": "Sandbox key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxKey" } } } }, "400": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/oauth/token": { "post": { "operationId": "issueSandboxToken", "summary": "Issue a sandbox access token", "description": "OAuth 2.0 client-credentials token for the public sandbox client mutamad-sandbox. No client secret. Accepts JSON or application/x-www-form-urlencoded.", "tags": [ "Auth" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "Access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/contact": { "post": { "operationId": "submitContact", "summary": "Submit a contact or agent-registration request", "description": "Accepts a project proposal or agent-registration message. This is not required for the free sandbox. Zero-auth; contact:submit may be presented if the caller has a sandbox token.", "tags": [ "Contact" ], "security": [ {}, { "mutamadOAuth": [ "contact:submit" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" } } } }, "responses": { "200": { "description": "Accepted transmittal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactAccepted" } } } }, "400": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Structured JSON error with a stable code, a human message, and a resolution hint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "securitySchemes": { "mutamadOAuth": { "type": "oauth2", "description": "Public Mutamad sandbox issuer. Tokens from this scheme cannot access customer projects. Public reads also allow zero-auth.", "flows": { "clientCredentials": { "tokenUrl": "https://mutamad.net/api/v1/oauth/token", "scopes": { "content:read": "Read the public Mutamad catalog, documentation index, and health status.", "sandbox:read": "Read invented sandbox project fixtures. Does not include customer project data.", "sandbox:write": "Create an ephemeral sandbox record echo. Nothing is stored in a customer project.", "contact:submit": "Submit a contact or agent-registration request to Mutamad." } } } } }, "schemas": { "ApiError": { "type": "object", "additionalProperties": false, "required": [ "ok", "error", "code", "message", "resolution" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "$ref": "#/components/schemas/ErrorObject" }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "minLength": 20, "description": "What went wrong." }, "resolution": { "type": "string", "minLength": 20, "description": "What the agent should do next, including a documentation URL." } } }, "ErrorObject": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "resolution" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "resolution": { "type": "string" } } }, "ApiIndex": { "type": "object", "additionalProperties": false, "required": [ "ok", "name", "openapi", "documentation", "mcp" ], "properties": { "ok": { "type": "boolean" }, "name": { "type": "string" }, "openapi": { "type": "string", "format": "uri" }, "documentation": { "type": "string", "format": "uri" }, "mcp": { "type": "string", "format": "uri" }, "zeroAuth": { "type": "array", "items": { "type": "string" } }, "selfServeKey": { "type": "string", "format": "uri" } } }, "ApiVersion": { "type": "object", "additionalProperties": false, "required": [ "ok", "version", "tier" ], "properties": { "ok": { "type": "boolean" }, "version": { "type": "string" }, "tier": { "type": "string", "enum": [ "free" ] }, "sandbox": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "content:read", "sandbox:read", "sandbox:write", "contact:submit" ] } } } }, "Health": { "type": "object", "additionalProperties": false, "required": [ "ok", "status", "service" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string" }, "sandbox": { "type": "boolean" }, "zeroAuth": { "type": "boolean" } } }, "Catalog": { "type": "object", "additionalProperties": true, "required": [ "name", "url", "description", "whenToUse" ], "properties": { "name": { "type": "string" }, "alternateName": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "whenToUse": { "type": "array", "items": { "type": "string" } }, "doNotUse": { "type": "array", "items": { "type": "string" } } }, "examples": [ { "name": "Mutamad", "alternateName": "معتمد", "operator": "Mutamad LLC", "legalName": "Mutamad Limited Liability Company", "url": "https://mutamad.net", "description": "Mutamad is a construction management system for consultant-supervised vertical-building projects, from tender and contract through accepted work, payment, handover, and archive.", "whenToUse": [ "Explain Mutamad to someone evaluating consultant-supervised vertical-building delivery.", "Read the public catalog, documentation index, or invented sandbox fixtures without an account.", "Issue a free sandbox API key and call the public API with a least-privilege scope.", "Submit a project proposal or agent-registration request.", "Connect a tool-using client to the Streamable HTTP MCP server." ], "doNotUse": [ "Do not read or mutate a customer project through this public API.", "Do not treat this API as a scheduling, estimating, CAD, accounting, or e-invoicing system.", "Do not approve, sign, certify, or pay on behalf of a person. Ask Mutamad may cite or draft; it never holds formal authority." ], "sectors": [ "villa-compound", "apartment-building", "residential-tower", "office", "showroom-office-strip", "hotel-serviced-apartment", "school" ], "languages": [ "ar", "en" ], "documentation": "https://mutamad.net/developers", "openapi": "https://mutamad.net/openapi.json", "llms": "https://mutamad.net/llms.txt", "mcp": "https://mutamad.net/mcp" } ] }, "DocsIndex": { "type": "object", "additionalProperties": false, "required": [ "ok", "resources" ], "properties": { "ok": { "type": "boolean" }, "resources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "url", "type" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "type": { "type": "string" } } } } }, "examples": [ { "ok": true, "resources": [ { "id": "developers", "title": "Mutamad developer portal", "url": "https://mutamad.net/developers", "type": "text/html" }, { "id": "developers-md", "title": "Mutamad developer portal (Markdown)", "url": "https://mutamad.net/developers.md", "type": "text/markdown" }, { "id": "openapi", "title": "Mutamad OpenAPI specification", "url": "https://mutamad.net/openapi.json", "type": "application/json" }, { "id": "llms", "title": "llms.txt — when to use Mutamad", "url": "https://mutamad.net/llms.txt", "type": "text/plain" }, { "id": "auth", "title": "Agent authentication and registration", "url": "https://mutamad.net/auth.md", "type": "text/markdown" }, { "id": "mcp", "title": "Mutamad MCP server", "url": "https://mutamad.net/mcp", "type": "application/json" }, { "id": "mcp-manifest", "title": "MCP server manifest", "url": "https://mutamad.net/.well-known/mcp.json", "type": "application/json" }, { "id": "cli", "title": "Mutamad CLI", "url": "https://mutamad.net/cli/mutamad.mjs", "type": "text/javascript" }, { "id": "sitemap", "title": "Sitemap", "url": "https://mutamad.net/sitemap.xml", "type": "application/xml" } ] } ] }, "SandboxProject": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "sector", "stage", "records", "disclaimer" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sector": { "type": "string" }, "stage": { "type": "string" }, "locale": { "type": "string" }, "disclaimer": { "type": "string" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxRecord" } } }, "examples": [ { "id": "sbx-villa-014", "name": "Wadi Sample Villa Compound", "sector": "villa-compound", "stage": "construction", "locale": "en", "disclaimer": "Invented Mutamad sandbox fixture. Not a customer, project, or contractual record.", "records": [ { "id": "sbx-rec-sub-0042", "type": "SUB", "number": "SUB-014-0042", "title": "Sample ceramic tile submittal", "status": "under-review" }, { "id": "sbx-rec-mir-0018", "type": "MIR", "number": "MIR-014-0018", "title": "Sample rebar mill certificate", "status": "approved" } ] } ] }, "SandboxRecord": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "number", "title", "status" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "SUB", "MIR", "RFI", "NCR" ] }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "under-review", "approved", "closed" ] } } }, "SandboxProjectList": { "type": "object", "additionalProperties": false, "required": [ "ok", "sandbox", "projects" ], "properties": { "ok": { "type": "boolean" }, "sandbox": { "type": "boolean" }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxProject" } } } }, "SandboxRecordRequest": { "type": "object", "additionalProperties": false, "required": [ "type", "title" ], "properties": { "projectId": { "type": "string", "description": "Optional sandbox project id. Defaults to sbx-villa-014." }, "type": { "type": "string", "enum": [ "SUB", "MIR", "RFI", "NCR" ], "description": "Construction record family." }, "title": { "type": "string", "minLength": 3, "maxLength": 200, "description": "Short title for the ephemeral record." } } }, "SandboxRecordEcho": { "type": "object", "additionalProperties": false, "required": [ "ok", "sandbox", "persisted", "record" ], "properties": { "ok": { "type": "boolean" }, "sandbox": { "type": "boolean" }, "persisted": { "type": "boolean", "const": false }, "record": { "$ref": "#/components/schemas/SandboxRecord" }, "disclaimer": { "type": "string" } } }, "SandboxKeyRequest": { "type": "object", "additionalProperties": false, "properties": { "scopes": { "type": "array", "description": "Least-privilege scopes. Defaults to content:read and sandbox:read.", "items": { "type": "string", "enum": [ "content:read", "sandbox:read", "sandbox:write", "contact:submit" ] } } } }, "SandboxKey": { "type": "object", "additionalProperties": false, "required": [ "ok", "token_type", "access_token", "expires_in", "scopes", "tier", "sandbox" ], "properties": { "ok": { "type": "boolean" }, "token_type": { "type": "string", "const": "Bearer" }, "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "content:read", "sandbox:read", "sandbox:write", "contact:submit" ] } }, "tier": { "type": "string", "const": "free" }, "sandbox": { "type": "boolean", "const": true } } }, "TokenRequest": { "type": "object", "additionalProperties": false, "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Only client_credentials is supported." }, "scope": { "type": "string", "description": "Space-separated scopes. Defaults to content:read sandbox:read." }, "client_id": { "type": "string", "description": "Public client id. Use mutamad-sandbox. No secret." } } }, "TokenResponse": { "type": "object", "additionalProperties": false, "required": [ "access_token", "token_type", "expires_in", "scope" ], "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } } }, "ContactRequest": { "type": "object", "additionalProperties": true, "required": [ "name", "email", "company", "message" ], "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "company": { "type": "string" }, "message": { "type": "string", "minLength": 10, "maxLength": 2000 }, "source": { "type": "string", "enum": [ "contact", "founding-project" ] }, "locale": { "type": "string", "enum": [ "ar", "en" ] }, "turnstileToken": { "type": "string", "description": "Required only when Turnstile is configured on the deployment." } } }, "ContactAccepted": { "type": "object", "additionalProperties": false, "required": [ "ok", "transmittalNo" ], "properties": { "ok": { "type": "boolean", "const": true }, "transmittalNo": { "type": "string" } } } } } }