# Quickstart

> Create an API key, then connect an AI agent over MCP or make your first call with the HTTP API.

Source: https://docs.fous.com/quickstart
Index: https://docs.fous.com/llms.txt

## Create an API key

Create a key in Studio under [API keys](https://app.fous.com/keys). Keep it in your environment, never in browser code or a repository.

```bash
export FOUS_API_KEY="fous_sk_..."
```

## With an AI agent

Tell your agent `set up https://fous.com/SKILL.md`. It gets its own key with your email, connects the MCP server and saves the skill, so it knows when to use Fous.

Or add Fous to Claude Code yourself, for every project. Run this again after you rotate the key.

```bash
claude mcp add --scope user --transport http fous https://api.fous.com/mcp \
  --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

Other clients: [Connect an AI agent](https://docs.fous.com/guides/mcp.md#connect-your-client). Then ask the agent:

```text
Which public holidays does Germany have in 2027?
```

## With the HTTP API

### Find a method

```bash
curl --get 'https://api.fous.com/v1/search' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  --data-urlencode 'query=public holidays in Germany next year'
```

Each result has the `slug` and the `input_schema` your input must fit.

```json
{
  "results": [
    {
      "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",
      "slug": "date.nager.at/list_public_holidays",
      "name": "List public holidays",
      "description": "Lists a country's public holidays for a year from Nager.Date, with local names, regional coverage and holiday types.",
      "returns": "date, weekday, English and local names, regions, type, nationwide flag",
      "platform": { "name": "Nager.Date", "domain": "nager.at" },
      "input_schema": {
        "type": "object",
        "required": ["country"],
        "properties": {
          "year": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9999,
            "description": "Calendar year, for example 2026. Defaults to the current year."
          },
          "country": {
            "type": "string",
            "description": "Country name or two-letter country code, for example Germany or DE."
          }
        }
      },
      "effect": "read",
      "auth": { "required": false },
      "cost": { "credits": 1 },
      "version": 2,
      "latest_version": 2
    }
  ],
  "match": "found"
}
```

### Run it

**cURL**

```bash
curl 'https://api.fous.com/v1/runs' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "date.nager.at/list_public_holidays",
    "input": {
      "country": "DE",
      "year": 2027
    }
  }'
```

**TypeScript**

```typescript
// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/runs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    method: 'date.nager.at/list_public_holidays',
    input: {
      country: 'DE',
      year: 2027
    }
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result.data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.fous.com/v1/runs",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    json={
        "method": "date.nager.at/list_public_holidays",
        "input": {
            "country": "DE",
            "year": 2027
        }
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result["data"])
```

### Read the result

```json
{
  "id": "run_01m5m0ere4fzdte37jhhn33ycd",
  "status": "completed",
  "method": {
    "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",
    "slug": "date.nager.at/list_public_holidays",
    "version": 2,
    "latest_version": 2
  },
  "data": {
    "country_name": "Germany",
    "year": 2027,
    "holidays": [
      {
        "date": "2027-01-01",
        "weekday": "Friday",
        "english_name": "New Year's Day",
        "local_name": "Neujahr",
        "nationwide": "yes",
        "regions": [],
        "type": "Public"
      },
      {
        "date": "2027-01-06",
        "weekday": "Wednesday",
        "english_name": "Epiphany",
        "local_name": "Heilige Drei Könige",
        "nationwide": "no",
        "regions": ["Baden-Württemberg", "Bavaria", "Saxony-Anhalt"],
        "type": "Public"
      }
    ]
  },
  "truncated": false,
  "cost": { "credits": 1 },
  "duration_ms": 1751
}
```

To skip the search, send a `query` instead of a `method` ([Run a query](https://docs.fous.com/guides/auto.md)).

## Next steps

- [Run a method](https://docs.fous.com/guides/runs.md): results, slow runs and failures.
- [Connect an account](https://docs.fous.com/guides/connections.md): run methods with your login.
- [Build a method](https://docs.fous.com/guides/builds.md): make one that does not exist yet.
- [API reference](https://docs.fous.com/api-reference.md): every endpoint.
