# Tool invocation

The unified gateway. One account, one token, one endpoint — every tool from every publisher.

## Endpoint

```
POST https://api.askfaro.com/invoke/{namespace}/{tool_name}
Authorization: Bearer faro_<your_key>
Content-Type: application/json

{
  "arguments": { ... },        // matches the tool's input_schema
  "idempotency_key": "..."     // optional; prevents duplicate charges on retry
}
```

## Auth

Three token types accepted on `/invoke`:

| Prefix | Use case | Extra headers |
|---|---|---|
| `faro_` | Personal / agent API key | — |
| `<JWT>` | Logged-in session | — |
| `faro_partner_` | Partner platform invoking for an end user | `X-Faro-User: <external_id>` |

Create a personal key: `POST https://api.askfaro.com/tokens/` (requires JWT from `POST https://api.askfaro.com/auth/login`).

## Response

```json
{
  "result": { ... },           // upstream tool output, as-is
  "credits_charged": 50,
  "credits_remaining": 9950,
  "invocation_id": "inv_..."
}
```

## Errors

| Code | Meaning |
|---|---|
| 401 | Missing or invalid token |
| 402 | Insufficient credits — call `POST /credits/purchase` |
| 404 | Namespace or tool not found |
| 409 | Duplicate `idempotency_key` |
| 502 | Upstream tool failed — auto-refunded when pricing is `charge_on: success` |

## Idempotency

Pass `idempotency_key` for any operation that has external side-effects (sending emails, posting messages, charging cards). Faro stores the first response keyed on that string for 24 hours and replays it on retries.

## Pricing modes

- `fixed_per_request` — Tool charges `fixed_credit_cost` per call.
- `tool_returned` — Tool returns its cost in the response (e.g. token-based pricing for LLM tools).

1,000 credits = $1.00 USD. The price shown on a listing is what you pay end-to-end; Faro's margin is bundled in.

## See also

- [CLI invocation](https://askfaro.com/llms/cli.md)
- OpenAPI spec: https://api.askfaro.com/openapi.json
- Structured guide (JSON): https://api.askfaro.com/docs/