A person clicks “Run” once. An agent can call the same endpoint a thousand times before anyone looks at the screen. Every run in Match Data Studio costs credits, so the first question about letting an agent use the API was not how to let it in. It was how to keep one confused loop from spending an account’s balance overnight.

This post is what we built to answer that, and where it still falls short.

What an agent can do today

The API is plain REST: HTTPS, JSON bodies, a bearer token. Humans writing scripts and agents calling tools use the same surface, which is the point. An agent needs no special protocol to talk to it.

The base address is https://api.match-data.studio/v1. Every response is either {"success": true, "data": ...} or {"success": false, "error": "..."}. These are the calls most workflows start with:

The calls a matching workflow is built from (paths relative to the base address)
CallPathWhat it does
POST/projectsCreate a project
POST/projects/{id}/filesUpload a CSV (multipart form)
PUT/projects/{id}/canvas-graphSave the pipeline as JSON
POST/projects/{id}/canvas-estimatePrice a run without starting it
POST/projects/{id}/canvas-runStart a sample or a full run (spends credits)
GET/runs/{id}Status and progress
POST/runs/{id}/stopStop a running run
GET/runs/{id}/downloadA link to the results file, valid for 15 minutes
GET/creditsBalance and history

A typical session is: create a project, upload the files, save a pipeline, price it, run a sample, look at the output, then run the full job and fetch the file. Nothing in that list needs a person, which is exactly why the next part matters.

What stands between an agent and your balance

None of these is clever. Each one closes a specific way an unattended caller can go wrong.

The guardrails, and what each one does not cover
GuardrailWhat it doesWhat it does not do
Tokens expireYou choose 30, 90, 180 days or a year when you create one. A token is shown once and stored only as a hash. At most 5 valid tokens per account.It does not narrow what the token can do while it is valid.
Some actions need a personA token cannot create or revoke tokens, buy credits, or manage your team. Those require a signed-in session.It can still start runs and delete projects.
Call limits120 requests per minute for each token and 10,000 calls per month for the account, only for token calls. Over a limit: 429 with Retry-After.It limits the number of calls, not their cost. One full run is one call.
A price before every runcanvas-estimate returns the most a run can use (and, when an earlier run of the same pipeline exists, what we expect it to use), and charges nothing. A sample run reads the first 50 rows of each file by default.An agent can skip the estimate. Nothing forces the order.
Credits are the ceilingA run is paid from the balance, so it cannot spend more than the account holds. A failed run is refunded in full.Whatever the balance holds can be spent.
StopPOST /runs/{id}/stop ends a run. The credits that finished steps used are kept, and the rest are returned.A step already in progress runs to its end, but you are not charged for it.

The honest reading of that table is the last column. The biggest gap today is that a token has the same reach as its owner, apart from the person-only actions. The server already understands narrower permissions, but the app does not offer them yet, so we are not claiming them. Until it does, the practical protection is the combination of a short-lived token and a small balance.

The limits, in detail

The limits are counted in shared storage, not in each server’s memory. The reason is how the API is served: requests can land on many servers at once, and a counter that lives in one server’s memory only counts the calls that server saw. A limit that works for one server and not for ten is not a limit.

Two behaviors are worth knowing before you write a client:

  • A call refused for the minute does not count toward the month. An agent that hits the per-minute limit and backs off does not burn its monthly allowance on the refusals. Calls with a bad token or without permission for the action are not counted at all.
  • We fail open. If the counter storage is unavailable, the call goes through. We chose availability over strictness: an outage on our side should not stop a customer’s job, and the credit balance remains the hard ceiling either way.

There is one known imprecision. The minute limit uses fixed one-minute windows, so a client can send up to twice the limit in a short burst that straddles two windows. For protecting an account from a runaway loop that is acceptable. For billing it would not be, which is why the limits count calls and the balance counts money.

Every response to a token call shows where you stand:

X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 117
X-RateLimit-Limit-Month: 10000
X-RateLimit-Remaining-Month: 9412

When a limit is hit, the answer looks like this, with a Retry-After header in seconds:

{
  "success": false,
  "code": "RATE_LIMITED",
  "error": "Rate limit exceeded: 120 requests per minute for each token. Try again in 23 seconds."
}

The monthly version has the code MONTHLY_LIMIT and tells you the date the count starts again.

What a well-behaved agent does

Price first, run a sample, and respect the limits. This is the pattern we would put in an agent’s instructions:

import time
import requests

BASE = "https://api.match-data.studio/v1"
HEADERS = {"Authorization": "Bearer mds_..."}
project_id = "..."  # from POST /projects

def call(method, path, **kwargs):
    while True:
        r = requests.request(method, BASE + path, headers=HEADERS, timeout=60, **kwargs)
        if r.status_code != 429:
            return r
        body = r.json()
        if body.get("code") == "MONTHLY_LIMIT":
            raise RuntimeError(body["error"])  # waiting will not help; tell a person
        time.sleep(int(r.headers.get("Retry-After", "5")))

estimate = call("POST", f"/projects/{project_id}/canvas-estimate", json={"type": "full"}).json()
# stop here and ask a person if estimate["data"]["max"] is more than you are willing to spend

The two details that matter are in the comments. A per-minute refusal is worth waiting out. A monthly refusal is not, and the right response is to stop and tell someone.

For the account itself, we suggest three things whenever an agent is involved: a token that expires in weeks, not a year; a balance of what the job needs, not what the account could hold; and a sample run before any full run.

Teaching an agent the API

A guardrail only helps if the agent follows it, and an agent only follows what it has read. So we publish three things, and none of them needs a token to read:

  • An OpenAPI description at https://api.match-data.studio/v1/openapi.json. Every call, its parameters, the scope a token needs for it, and the error answers. Client generators and agent frameworks can read it directly.
  • A step catalog at https://api.match-data.studio/v1/canvas/node-catalog. Every step a pipeline can use, with its ports, its settings, an example of each, and whether it costs credits, plus three complete example pipelines. Add ?format=md for a compact text version. This is what lets an agent build a pipeline instead of being handed one.
  • An agent skill at https://api.match-data.studio/v1/skill. A SKILL.md file that teaches the workflow and the rules in this post: price before every run, sample first, ask a person before a full run, back off on a 429. It does not copy the step list; it tells the agent to read the live catalog, so a skill you installed last month does not go stale.

To install the skill for a coding agent:

mkdir -p .claude/skills/match-data-studio
curl -s https://api.match-data.studio/v1/skill -o .claude/skills/match-data-studio/SKILL.md

We keep these from drifting with tests, not with discipline. A route a token can call but the description does not mention fails our test suite. So does a step in the editor that is missing from the catalog, and an example pipeline that our own validator rejects.

What we have not built

We would rather list this than imply it:

  • Narrower tokens in the app, for example read-only. The server supports the idea; the app does not offer it. Until it does, the protection is a short-lived token and a small balance.
  • Enforced ordering. Nothing forces an agent to price a run before starting it. The skill asks for it, and the balance limits the damage, but the API will start a run you did not price.

Keep reading