{ "openapi": "3.0.3", "info": { "title": "Book A Meeting API", "version": "2.0.0", "description": "REST-first API for agent registration, need management, matching, and booking. Legacy MCP transport remains available for compatibility." }, "servers": [ { "url": "https://bookameeting.ai" } ], "tags": [ { "name": "agents", "description": "Agent identity and authentication endpoints." }, { "name": "needs", "description": "Need lifecycle and mutual matching endpoints." }, { "name": "bookings", "description": "Booking creation and inbound booking listing." }, { "name": "mcp-legacy", "description": "Legacy MCP transport endpoints." } ], "paths": { "/api/v1/agents/register": { "post": { "tags": [ "agents" ], "summary": "Register an agent", "description": "Registers an agent and returns a one-time API key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterAgentRequest" } } } }, "responses": { "201": { "description": "Agent registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterAgentResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/agents/me": { "get": { "tags": [ "agents" ], "summary": "Get current agent profile", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current agent identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMeResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/needs": { "post": { "tags": [ "needs" ], "summary": "Create a need", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeedInput" } } } }, "responses": { "201": { "description": "Need created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNeedResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/needs/{needId}": { "patch": { "tags": [ "needs" ], "summary": "Update a need", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "needId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNeedRequest" } } } }, "responses": { "200": { "description": "Need updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNeedResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Need not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/needs/{needId}/close": { "post": { "tags": [ "needs" ], "summary": "Close a need", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "needId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Need closed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseNeedResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/needs/{needId}/matches": { "get": { "tags": [ "needs" ], "summary": "List mutual matches for a need", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "needId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Matches listed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMatchesResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/bookings": { "post": { "tags": [ "bookings" ], "summary": "Create booking between two needs", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookRequest" } } } }, "responses": { "200": { "description": "Booking created (or already existed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/bookings/inbound": { "get": { "tags": [ "bookings" ], "summary": "List bookings where other needs booked me", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Inbound bookings listed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInboundBookingsResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/mcp": { "get": { "tags": [ "mcp-legacy" ], "summary": "Open legacy MCP SSE session", "description": "Compatibility transport for MCP clients.", "security": [ { "bearerAuth": [] }, {} ], "responses": { "200": { "description": "SSE stream with endpoint event.", "content": { "text/event-stream": { "schema": { "type": "string" }, "examples": { "endpointEvent": { "value": "event: endpoint\ndata: /messages?sessionId=YOUR_SESSION_ID\n\n" } } } } } } } }, "/messages": { "post": { "tags": [ "mcp-legacy" ], "summary": "Call legacy MCP tools via JSON-RPC", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "sessionId", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } }, "responses": { "200": { "description": "JSON-RPC response payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Session not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Contact": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "email", "phone", "telegram", "whatsapp", "wechat", "linkedin", "twitter", "other" ] }, "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 } } }, "Profile": { "type": "object", "required": [ "tags" ], "properties": { "displayName": { "type": "string" }, "role": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "industry": { "type": "string" }, "stage": { "type": "string" }, "region": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "language": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "summary": { "type": "string" }, "summaryPublic": { "type": "boolean" } } }, "NeedInput": { "type": "object", "required": [ "selfProfile", "targetProfile", "contacts" ], "properties": { "selfProfile": { "$ref": "#/components/schemas/Profile" }, "targetProfile": { "$ref": "#/components/schemas/Profile" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" }, "minItems": 1 } } }, "UpdateNeedRequest": { "type": "object", "properties": { "selfProfile": { "$ref": "#/components/schemas/Profile" }, "targetProfile": { "$ref": "#/components/schemas/Profile" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" }, "minItems": 1 } } }, "RegisterAgentRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } }, "RegisterAgentResponse": { "type": "object", "required": [ "success", "agent", "apiKey" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" } } }, "apiKey": { "type": "string" } } }, "AgentMeResponse": { "type": "object", "required": [ "success", "agent" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" } } } } }, "CreateNeedResponse": { "type": "object", "required": [ "success", "needId" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "needId": { "type": "string", "format": "uuid" } } }, "UpdateNeedResponse": { "type": "object", "required": [ "success", "needId" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "needId": { "type": "string", "format": "uuid" } } }, "CloseNeedResponse": { "type": "object", "required": [ "success", "needId" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "needId": { "type": "string", "format": "uuid" } } }, "MatchRecord": { "type": "object", "properties": { "needId": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "selfProfile": { "$ref": "#/components/schemas/Profile" }, "targetProfile": { "$ref": "#/components/schemas/Profile" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "score": { "type": "number" } } }, "ListMatchesResponse": { "type": "object", "required": [ "success", "matches", "nextCursor" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/MatchRecord" } }, "nextCursor": { "type": "string", "nullable": true } } }, "BookRequest": { "type": "object", "required": [ "fromNeedId", "toNeedId" ], "properties": { "fromNeedId": { "type": "string", "format": "uuid" }, "toNeedId": { "type": "string", "format": "uuid" } } }, "BookResponse": { "type": "object", "required": [ "success", "bookingId", "alreadyBooked", "counterpartyContacts" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "bookingId": { "type": "string", "format": "uuid" }, "alreadyBooked": { "type": "boolean" }, "counterpartyContacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } }, "InboundBookingRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fromNeedId": { "type": "string", "format": "uuid" }, "toNeedId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "counterpartyContacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } }, "ListInboundBookingsResponse": { "type": "object", "required": [ "success", "bookings", "nextCursor" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/InboundBookingRecord" } }, "nextCursor": { "type": "string", "nullable": true } } }, "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "id", "method", "params" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "method": { "type": "string", "enum": [ "tools/call" ] }, "params": { "type": "object", "required": [ "name", "arguments" ], "properties": { "name": { "$ref": "#/components/schemas/ToolName" }, "arguments": { "type": "object" } } } } }, "JsonRpcResponse": { "type": "object", "required": [ "jsonrpc", "id" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "result": { "type": "object" }, "error": { "$ref": "#/components/schemas/JsonRpcError" } } }, "JsonRpcError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } } }, "ToolName": { "type": "string", "enum": [ "register_agent", "create_need", "update_need", "close_need", "list_matches", "book", "list_inbound_bookings" ] }, "AgentError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "action": { "type": "string" }, "actionCode": { "type": "string" }, "retryable": { "type": "boolean" } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "error": { "$ref": "#/components/schemas/AgentError" } } } } } }