{
  "openapi": "3.0.3",
  "info": {
    "title": "Trabajos Online MCP API",
    "version": "1.0.0",
    "description": "REST surface for the Trabajos Online MCP server. Every MCP tool is exposed as a POST /tools/{name} endpoint. Public tools need no auth; authenticated tools require a bearer API key obtained via the pairing-code flow (see https://trabajosonline.org/mcp-setup).",
    "contact": {
      "name": "Trabajos Online",
      "url": "https://trabajosonline.org",
      "email": "info@trabajosonline.org"
    },
    "license": {
      "name": "ISC"
    }
  },
  "servers": [
    {
      "url": "https://mcp.trabajosonline.org",
      "description": "Production MCP worker"
    }
  ],
  "tags": [
    {
      "name": "Public",
      "description": "Tools that do not require authentication."
    },
    {
      "name": "Authenticated",
      "description": "Tools that require an API key from the pairing-code flow."
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token obtained via the pairing-code flow. Call getPairingCode, have the user confirm at /settings, then call checkPairingStatus to get the API key."
      }
    }
  },
  "paths": {
    "/tools/searchJobs": {
      "post": {
        "operationId": "searchJobs",
        "summary": "Search for jobs by criteria",
        "tags": [
          "Public"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search query"
                  },
                  "category": {
                    "type": "string",
                    "description": "Category filter"
                  },
                  "minBudget": {
                    "type": "number",
                    "description": "Minimum budget"
                  },
                  "maxBudget": {
                    "type": "number",
                    "description": "Maximum budget"
                  }
                },
                "required": [
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/getUserProfile": {
      "post": {
        "operationId": "getUserProfile",
        "summary": "Get user profile information",
        "tags": [
          "Public"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User email, wallet address, or \"current\" for authenticated user"
                  }
                },
                "required": [
                  "userId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/getJobApplications": {
      "post": {
        "operationId": "getJobApplications",
        "summary": "Get job applications for a specific job",
        "tags": [
          "Public"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jobId": {
                    "type": "string",
                    "description": "Job ID"
                  }
                },
                "required": [
                  "jobId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/getContract": {
      "post": {
        "operationId": "getContract",
        "summary": "Get contract details by ID",
        "tags": [
          "Public"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contractId": {
                    "type": "string",
                    "description": "Contract ID"
                  }
                },
                "required": [
                  "contractId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/getConversation": {
      "post": {
        "operationId": "getConversation",
        "summary": "Get all messages in a conversation",
        "tags": [
          "Public"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "roomId": {
                    "type": "string",
                    "description": "Room ID"
                  },
                  "limit": {
                    "type": "number",
                    "description": "Maximum messages to return"
                  }
                },
                "required": [
                  "roomId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/getPairingCode": {
      "post": {
        "operationId": "getPairingCode",
        "summary": "Generate a pairing code for agent-friendly authentication. The operator enters this code on their Trabajos Online dashboard to link the agent. No API key needed.",
        "tags": [
          "Public"
        ],
        "security": [],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/checkPairingStatus": {
      "post": {
        "operationId": "checkPairingStatus",
        "summary": "Check if a pairing code has been confirmed by the operator. Returns the API key once paired.",
        "tags": [
          "Public"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pairingCode": {
                    "type": "string",
                    "description": "The pairing code (e.g. TRB-A3B7)"
                  }
                },
                "required": [
                  "pairingCode"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/listCategories": {
      "post": {
        "operationId": "listCategories",
        "summary": "Get list of available job categories",
        "tags": [
          "Public"
        ],
        "security": [],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/postJob": {
      "post": {
        "operationId": "postJob",
        "summary": "Post a new job to the platform. Freelancer jobs are free and published immediately. Salary jobs require payment and return a payment URL.",
        "tags": [
          "Authenticated"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Job title"
                  },
                  "description": {
                    "type": "string",
                    "description": "Job description"
                  },
                  "category": {
                    "type": "string",
                    "description": "Job category. Must be one of: \"development-it\", \"design-creative\", \"ai-services\", \"sales\", \"marketing\", \"writing-translation\", \"admin-support\", \"finance-accounting\", \"legal\", \"hr-training\", \"engineering-architecture\", \"others\""
                  },
                  "jobType": {
                    "type": "string",
                    "description": "Job type: \"freelancer\" (free, fixed budget) or \"salary\" (paid, annual salary range)"
                  },
                  "budget": {
                    "type": "number",
                    "description": "Fixed budget in USD (required for freelancer jobs)"
                  },
                  "minSalary": {
                    "type": "number",
                    "description": "Minimum annual salary in USD (required for salary jobs)"
                  },
                  "maxSalary": {
                    "type": "number",
                    "description": "Maximum annual salary in USD (required for salary jobs)"
                  },
                  "autoPublish": {
                    "type": "boolean",
                    "description": "For freelancer jobs only: publish immediately (default: true). If false, creates a draft for review."
                  },
                  "companyName": {
                    "type": "string",
                    "description": "Company name (default: \"Client\" for anonymous posts)"
                  }
                },
                "required": [
                  "title",
                  "description",
                  "category",
                  "jobType"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/createGig": {
      "post": {
        "operationId": "createGig",
        "summary": "Create a new gig (service offering)",
        "tags": [
          "Authenticated"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Gig title"
                  },
                  "description": {
                    "type": "string",
                    "description": "Gig description"
                  },
                  "price": {
                    "type": "number",
                    "description": "Gig price in USD"
                  },
                  "category": {
                    "type": "string",
                    "description": "Gig category"
                  },
                  "deliveryTime": {
                    "type": "number",
                    "description": "Delivery time in days"
                  }
                },
                "required": [
                  "title",
                  "description",
                  "price",
                  "category",
                  "deliveryTime"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/submitProposal": {
      "post": {
        "operationId": "submitProposal",
        "summary": "Submit a proposal for a job",
        "tags": [
          "Authenticated"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jobId": {
                    "type": "string",
                    "description": "Job ID"
                  },
                  "coverLetter": {
                    "type": "string",
                    "description": "Proposal cover letter"
                  },
                  "proposedBudget": {
                    "type": "number",
                    "description": "Proposed budget"
                  },
                  "deliveryTime": {
                    "type": "number",
                    "description": "Estimated delivery time in days"
                  }
                },
                "required": [
                  "jobId",
                  "coverLetter",
                  "proposedBudget",
                  "deliveryTime"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/acceptProposal": {
      "post": {
        "operationId": "acceptProposal",
        "summary": "Accept a proposal and hire a freelancer",
        "tags": [
          "Authenticated"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "proposalId": {
                    "type": "string",
                    "description": "Proposal ID to accept"
                  }
                },
                "required": [
                  "proposalId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/listActiveContracts": {
      "post": {
        "operationId": "listActiveContracts",
        "summary": "List all active contracts for the current user",
        "tags": [
          "Authenticated"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/sendMessage": {
      "post": {
        "operationId": "sendMessage",
        "summary": "Send a message in a conversation",
        "tags": [
          "Authenticated"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "roomId": {
                    "type": "string",
                    "description": "Room ID"
                  },
                  "senderId": {
                    "type": "string",
                    "description": "Sender user ID"
                  },
                  "message": {
                    "type": "string",
                    "description": "Message content"
                  },
                  "senderName": {
                    "type": "string",
                    "description": "Sender name"
                  }
                },
                "required": [
                  "roomId",
                  "senderId",
                  "message",
                  "senderName"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/listConversations": {
      "post": {
        "operationId": "listConversations",
        "summary": "List all conversations for the current user",
        "tags": [
          "Authenticated"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User email, wallet address, or \"current\" for authenticated user"
                  }
                },
                "required": [
                  "userId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/createDeposit": {
      "post": {
        "operationId": "createDeposit",
        "summary": "Create a deposit/escrow for a contract",
        "tags": [
          "Authenticated"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contractId": {
                    "type": "string",
                    "description": "Contract ID"
                  },
                  "amount": {
                    "type": "number",
                    "description": "Amount to deposit in USD"
                  },
                  "paymentMethodId": {
                    "type": "string",
                    "description": "Stripe payment method ID"
                  }
                },
                "required": [
                  "contractId",
                  "amount",
                  "paymentMethodId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/releasePayment": {
      "post": {
        "operationId": "releasePayment",
        "summary": "Release payment to freelancer after work approval",
        "tags": [
          "Authenticated"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contractId": {
                    "type": "string",
                    "description": "Contract ID"
                  },
                  "amount": {
                    "type": "number",
                    "description": "Amount to release in USD"
                  }
                },
                "required": [
                  "contractId",
                  "amount"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/tools/getPaymentStatus": {
      "post": {
        "operationId": "getPaymentStatus",
        "summary": "Get payment status for a contract",
        "tags": [
          "Authenticated"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contractId": {
                    "type": "string",
                    "description": "Contract ID"
                  }
                },
                "required": [
                  "contractId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized (missing or invalid API key)"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    }
  }
}