Developer Reference

API Docs

Stream AI-grounded Irish data reports from any agent via our REST API.

Overview

The Irish Decision Agents API lets you programmatically run any built-in or custom agent and receive a real-time NDJSON stream of events — from data-fetch steps through to the final scored output.

Base URL: https://agents.irishmcp.ie/api/v1

Response format: NDJSON (newline-delimited JSON) — one JSON object per line, streamed as the run progresses.

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer ida_YOUR_KEY_HERE

API keys start with the prefix ida_. Generate a key in your dashboard →

Rate limits

Tier	Limit
Explorer (free)	10 calls / day
Pro (€19/mo)	500 calls / day
Growth (€49/mo)	2,000 calls / day

Limits reset daily at midnight UTC. On 429, the response body includes used and limit fields.

Endpoint reference

POST/api/v1/agents/{slug}/run

Path parameters

Param	Type	Description
slug	string	The agent slug (e.g. `should-i-move-here`)

Request body

JSON object containing the agent's input fields. See the Available agents table below for each agent's fields.

Response event types

The response is a streaming NDJSON body. Each line is a JSON object with a type field:

type	Description
run_created	Run successfully created; contains run_id
step_start	An MCP data-fetch step has begun
step_done	A step completed successfully; includes result_preview
step_error	A step failed (agent continues with remaining steps)
synthesis_start	LLM synthesis has started
done	Run complete; contains full output object
error	Fatal error; run aborted

Final `done` event shape

{
  "type": "done",
  "run_id": "uuid",
  "output": {
    "overall_score": 72,
    "priority_scores": { "affordability": 65, "commute": 80 },
    "narrative_md": "## Summary\n...",
    "warnings": [],
    "sources": [
      { "mcp": "property-price", "tool": "", "retrieved_at": "..." }
    ]
  }
}

Code examples

curl

curl -X POST \
  https://agents.irishmcp.ie/api/v1/agents/should-i-move-here/run \
  -H "Authorization: Bearer ida_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "area": "Dublin 4",
    "household": { "adults": 2, "children": 0, "pets": false },
    "priorities": ["affordability", "commute", "healthcare"]
  }'

JavaScript (fetch)

const res = await fetch(
  'https://agents.irishmcp.ie/api/v1/agents/should-i-move-here/run',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ida_YOUR_KEY_HERE',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      area: 'Dublin 4',
      household: { adults: 2, children: 0, pets: false },
      priorities: ['affordability', 'commute'],
    }),
  }
);

const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  for (const line of decoder.decode(value).split('\n')) {
    if (line.trim()) {
      const event = JSON.parse(line);
      console.log(event.type, event);
    }
  }
}

Python (requests)

import requests, json

response = requests.post(
    'https://agents.irishmcp.ie/api/v1/agents/should-i-move-here/run',
    headers={
        'Authorization': 'Bearer ida_YOUR_KEY_HERE',
        'Content-Type': 'application/json',
    },
    json={
        'area': 'Dublin 4',
        'household': {'adults': 2, 'children': 0, 'pets': False},
        'priorities': ['affordability', 'commute'],
    },
    stream=True,
)

for line in response.iter_lines():
    if line:
        event = json.loads(line)
        print(event['type'], event)

Available agents

Slug	Name	Tier	Input fields
`should-i-move-here`	Should I Move Here?	FREE	area (string), household.adults (int), household.children (int), household.pets (bool), priorities (string[]), commute_destination (string, optional)
`is-this-a-good-property`	Is This a Good Property?	FREE	location (string), asking_price (number), property_type (house \| apartment \| site \| other)
`where-should-i-locate-my-business`	Where Should I Locate My Business?	PRO	business_type (string), headcount (int), preferred_region (string), budget_monthly_eur (number, optional)
`what-are-my-tds-up-to`	What Are My TDs Up To?	FREE	query (string — TD name or constituency)
`should-i-take-this-job`	Should I Take This Job?	FREE	job_title (string), company_location (string), offered_salary (number), current_location (string, optional), priorities (string[])
`is-this-a-good-time-to-buy`	Is This a Good Time to Buy?	FREE	area (string), budget (number), household_income (number), property_type (apartment \| house \| any)

Error codes

HTTP status	Meaning
`401`	Invalid or missing API key. Include Authorization: Bearer <key> header.
`404`	Agent slug not found or inactive.
`429`	Rate limit exceeded. Response body includes { "error": "rate_limit_exceeded", "used": N, "limit": N }.
`403`	Agent requires a higher subscription tier.
`500`	Internal server error. Run is created but may fail during synthesis.

Ready to build?

Get an API key →Try an agent