Describe a REST API

Connect a system that has a REST API but no MCP server, with an api block in a pack: read tools only, mapped answers, limits.

Many systems, most affiliate trackers among them, have an ordinary REST API but no MCP server. A profile's api block describes such an API as a set of read tools, and ChatPilot's own engine calls it. To the rest of ChatPilot the system then looks like any other: the client card, monitors, reports, live figures for auto-answer and discussions all work. The Everflow, Affise and Scaleo packs that come with ChatPilot are built this way.

What the engine holds, whatever the pack says

Read only. A tool is a GET, or a POST marked read: true for a report query that only reads. Tool names that sound like writing (create_…, update_…, pause_…) are refused.
Only what you map reaches the AI. Each answer is cut down to the fields in returns.
The key stays in the secret store. It is never put in an error, a log or the AI's view.
Limits. A timeout per request, requests per minute, a cap on the answer's size and on list length, no redirects, and https:// only (plain http:// only to this computer).

The address and the key

api:
  base_url: https://{domain}/api/v1
  auth: {type: header, name: X-Api-Key}
  check: list_offers
  limits: {timeout: 20, per_minute: 30}

base_url: only the host may hold {fields}, such as {domain} for a system where every customer has their own address. The owner fills them in when connecting.
auth: {type: header, name: …}, bearer, basic (the key is user:password), {type: query, name: …} (only when the API offers nothing else) or none.
check: a tool without required arguments, called once when connecting, so a wrong address or key is reported at once and nothing is saved.
limits (optional): timeout in seconds (at most 60), per_minute, max_bytes, max_items.

The tools

  tools:
    find_affiliates:
      about: Affiliates by e-mail or name
      path: /affiliates
      params:
        q: {type: string, required: true, name: search}
      fixed: {per_page: 20}
      items: data.rows
      returns: {id: id, name: name, email: contact.email, status: status}

Key	What
the name	lowercase letters, digits and `_`, saying what it reads. The AI sees it
`about`	one line for the AI: what the tool gives
`path`	appended to `base_url`. A `{name}` in it is a required argument, escaped so it stays in its place
`params`	the arguments: `type` (`string`, `integer`, `number`, `boolean` or `date`), `required`, `name` (the API's own name), `in` (`query` or `body`), `options`, `default`. Name period arguments `from` and `to`
`fixed`	values always sent: page sizes, a report's columns
`items`	where the list is in the answer, for a tool that returns one
`returns`	`our_name: path.in.the.answer`. Only these fields are kept

A report that only works as a POST gets method: POST and read: true, with the fixed part of the body in fixed. In a body, dots in a name nest, and a number steps into a list that fixed already holds (filters.0.value).

The rest of the profile

The api block only gives the tools. The profile around it says what they mean, as in Write a profile or a pack: the category (a tracker is ad_platform), the account with its lookup on the find tool, the roles (which may only name the block's own tools), the card, monitors, reports and autopilot_answers. A profile with an api block needs no matches.

Try it

Check and install the pack, then connect it in config.yaml with the key in the secret store:

discuss:
  mcp:
    - name: tracker
      title: "My tracker"
      api: example-tracker
      api_fields: {domain: tracker.example.com}

chatpilot profiles check my-pack/
chatpilot profiles install my-pack/
chatpilot secret set mcp_tracker_key
chatpilot mcp

chatpilot mcp shows the source, its tools and what it may read. In the panel, the system's What ChatPilot understood shows the profile it got and any role that is missing. Bind a test chat to an account and look at its client card.

Writing through a REST API (changing caps, payouts or offers) isn't possible yet.

Checked against ChatPilot 0.1.0b1. Report a problem with this page