Master the REST API Tool

The REST API tool connects your Mates to any service that has a REST API, even when no ready-made tool or MCP server exists. You describe the API in an OpenAPI schema, add the credentials it needs as request headers or setup fields, and the Mate calls the endpoints you declared. This article is for the people who build tools: it shows the creation dialog, the headers table and how to write a schema that a Mate uses well. The Tool Builder Mate from the Mates Store writes the OpenAPI schema for you from the API documentation: see Tool Building Resources.

Creating a tool needs tool-management rights: the Expert plan by default; your organization's plans may differ. If the service publishes an MCP server, use it instead: see "Deploying a Custom MCP Server in Your Organization".

Create a REST API tool

1. In the sidebar, open Mates & tools, then Toolbox.

2. Click Connect tool, then Add custom tool. The dialog opens on the MCP setup.

3. Click Other custom tool paths, then REST API. The Add custom REST API dialog opens: "Paste the OpenAPI schema, then add credentials only if the API needs headers."

4. Paste your schema in OpenAPI Schema (YAML).

5. If the API needs credentials, open Advanced settings and fill in the headers and setup fields (next section).

6. Click Install.

The app reads your schema and sets the name, description and icon of the tool for you. A toast confirms it: "Info detected automatically". Rename the tool afterwards if a colleague would not recognize it. Then the tool attachment dialog opens: click the Mates that need the tool and click Save access.

You can also start from the Tools Store: click Create custom tool.

Add credentials: headers and setup fields

Advanced settings ("Authentication, request headers, and optional setup fields.") holds three parts.

Auth preset. Bearer Token adds an Authorization header row with the Bearer prefix for you. No Auth leaves the headers as you set them.

Headers. Click Add custom header for each header the API expects. Each row has these columns:

The Scope decides who provides the value:

• Fixed value: a constant written in the tool settings, visible to anyone who edits the tool. Use it for non-secret values only, such as Accept: application/json.

• Organization: one value for everyone, entered by an organization admin in the tool settings.

• Member: each member enters their own value the first time a Mate needs the tool.

Choose Sensitive for any secret: the value is masked.

Custom parameters. Click Add parameter for a value that is not a header, such as an API key in the URL or a tenant ID. It has the same scopes. Reference it in the schema with a placeholder: {{organization.toolInstance.<key>}} for an Organization value, {{member.toolInstance.<key>}} for a Member value. The full syntax is in "Placeholders Reference: Injecting Context Into Your Tools and Mates".

For example, an API that expects its key as a query parameter:

parameters:
  - name: key
    in: query
    required: true
    description: |
      API key.
      ## For LLMs
      - Use the exact value. Do not change or invent it.
    schema:
      type: string
    enum: ['{{organization.toolInstance.weatherApiKey}}']

with a custom parameter whose Placeholder key is weatherApiKey and whose Scope is Organization.

Write a schema that a Mate uses well

The REST API tool reads an OpenAPI 3 document: info, servers (the base URL), paths with one operation per endpoint, and their parameters, requestBody and responses. The Mate only sees what the schema declares, so the schema is also its manual.

You do not have to write it by hand: the Tool Builder Mate from the Mates Store writes the schema from the API documentation, following the rules below. See Tool Building Resources.

• Give every operation a clear operationId and description.

• Describe every parameter: format, allowed values, whether it is required.

• Add a ## For LLMs section in descriptions for rules the Mate must follow.

• Declare only the endpoints the Mate needs.

paths:
  /customers/{customerId}:
    get:
      operationId: getCustomerDetails
      summary: Retrieve customer details
      description: |
        Gets the contact information and account status of one customer.
        ## For LLMs
        - The customerId must come from the CRM. Do not invent IDs.
      parameters:
        - name: customerId
          in: path
          required: true
          description: Unique customer identifier, for example "CUST12345".
          schema:
            type: string

With this operation, a member can ask: "What is the contact information for customer CUST12345?"

To send files attached in the chat, see "Handling File Uploads in REST API Tools". To shape what the API returns to the Mate, see "Handling REST API Tools Response".

Edit the tool

In the Toolbox, open the tool menu (⋮) and click Edit. The Settings tab holds the name, descriptions, OpenAPI Schema and Advanced settings. The tool page also shows the OpenAPI Schema tab, read-only. Only the tool Owner can save changes.

Good to know

• Older REST tools show Legacy runtime preserved: the name and descriptions stay editable, but headers, custom parameters, authentication, URL and schema are locked. Click Create a new clean instance to re-enter them, secrets included, in the current format.

• Test with a Mate after each change: a clear request that needs the endpoint, then a request that should fail.

• Keep an eye on the provider's rate limits. A Mate may call an endpoint several times in one reply.

Related articles

• Personal and shared tool authentication

• Placeholders Reference: Injecting Context Into Your Tools and Mates

• Handling File Uploads in REST API Tools

• Handling REST API Tools Response

• Creating and Managing Tool Instances

• Tool Building Resources