Fous Docs
Open Studio
FousDocs
esc
Studio

Quickstart

Create an API key and make your first tool call in five minutes.

1. Create an API key

Sign in to Fous Studio. Open Developers at the bottom of the window, turn on Developer mode, then select API keys and create a key. Keys belong to the organization you are in; its credits, limits and connected accounts apply to every call.

Store the key as FOUS_API_KEY in your server environment. Never put it in browser code or a repository.

Terminal
export FOUS_API_KEY="fous_sk_..."

2. Pick a tool

Every public tool has a handle such as @hacker-news and one or more operations with a typed input. Search the catalog without a key:

Terminal
curl --get 'https://api.fous.com/v1/catalog' --data-urlencode 'query=hacker news'

The result lists each tool's api handle and its operations. Open one in the catalog to read its input schema and verified examples: GET /v1/catalog/detail?api=@hacker-news. Find a tool explains the filters.

3. Call it

Send the handle, the operation and an input that matches its schema. Add an Idempotency-Key so that a retried request returns the same result instead of running and charging again.

Terminal
curl 'https://api.fous.com/v1/query' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H "Idempotency-Key: $FOUS_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"api":"@hacker-news","operation":"list_front_page","input":{"list_name":"show_hn","max_results":5}}'

The Python example uses the requests package (pip install requests). Node.js 18 or later has fetch built in.

4. Read the result

Check the HTTP status and success, then read data.output. The receipt tells you what ran and what it cost.

JSON
{
  "success": true,
  "data": {
    "output": {
      "stories": [
        {
          "rank": 1,
          "title": "Show HN: Jeff – Jev-compatible 0.8B decision models, trained at home",
          "author": "firelex",
          "points": 230,
          "item_id": 49883844,
          "posted_at": "2026-09-28T20:23:36Z",
          "website_link": "https://github.com/firelex/jeff",
          "comment_count": 79,
          "discussion_link": "https://news.ycombinator.com/item?id=49883844"
        }
      ]
    },
    "receipt": {
      "request_id": "req_mg7x9f2kQ1nTz8bW3pLc0RhV",
      "api": "@hacker-news",
      "operation": "list_front_page",
      "billing": { "status": "settled", "reserved_credits": 1, "charged_credits": 1 }
    }
  }
}

A failure returns success: false and an error with a code to branch on. Errors and limits lists every code.

5. Keep the request ID

The receipt's request_id (also sent as the X-Request-Id header) identifies the run. Look it up at any time without running the tool again:

Terminal
curl "https://api.fous.com/v1/query/requests/$FOUS_REQUEST_ID" \
  -H "Authorization: Bearer $FOUS_API_KEY"

After a timeout or a dropped connection, retry with the same body and the same idempotency key. Use a new key when you want fresh data. Retries and idempotency.

Next steps