# Gateway endpoints

Call any of 947 provider endpoints with one key: search the catalogue, send the provider's own parameters, pay per call.

Verified jobs (`POST /v1/execute`) cover the work where a wrong answer costs you: Arettic picks the tool, checks the result and charges only if it passes. Everything else your agent needs goes through the gateway: 947 endpoints from 70 providers (840 live now), with the same key and the same balance. You send the provider's own parameters, you get the provider's own answer, and you pay per call. A call the provider fails or times out costs nothing.

## 1. Find an endpoint

Search the catalogue with no key. Every word must match the id, provider or name; filter by `category`, `provider` or `availability`. Each endpoint has an `id`, its `method` and `path`, the `path_params` it needs and its `price_per_call`. The whole list is also on [Endpoints](/endpoints).

**curl**

```bash
curl "https://api.arettic.com/v1/endpoints?q=google+maps"
```

Categories

| category | What's in it |
|---|---|
| `people` | Emails, phone numbers, people search and enrichment, LinkedIn profiles. |
| `companies` | Firmographics, funding, hiring and job posts, tech stack, lookalikes, reviews, news. |
| `search` | Google results, maps, news, scholar and patents, AI answers, deep research. |
| `scrape` | Any page as markdown or JSON, whole-site crawls, screenshots, browser automation. |
| `social` | LinkedIn, X, TikTok, Instagram, YouTube and Reddit data; ad libraries; creators. |
| `finance` | Financial statements, SEC filings, insider trades, stock prices, earnings. |
| `brands` | Logos, colours, fonts, styleguides, products and industry codes from a domain. |
| `ai` | Chat models, embeddings, speech to text, text to speech, music and image generation. |
| `utilities` | VAT checks, exchange rates, time zones, public holidays, hyperlocal weather. |
| `identity` | AML screening, database validation, phone and email codes. |
| `messaging` | Agent inboxes, SMS and phone agents. |
| `compute` | Machines that run code and commands for an agent. |

## 2. Call it

`POST /v1/call` with the endpoint's `id`, plus `query` (for GET endpoints), `body` (for POST endpoints) and `path_params` (for each `{name}` in the path), exactly as the provider's API takes them. Send `max_price` in credits to refuse anything dearer.

**curl**

```bash
curl https://api.arettic.com/v1/call \
  -H "Authorization: Bearer $ARETTIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endpoint": "serper/google-maps-search", "body": {"q": "coffee in Bangalore"}}'
```

**TypeScript**

```ts
const r = await client.call({
  endpoint: "predictleads/company-job-openings",
  path_params: { company_id_or_domain: "stripe.com" },
});
console.log(r.status, r.charged, r.data);
```

**Python**

```python
r = client.call(endpoint="serper/google-news-search", body={"q": "AI agent funding"})
print(r["status"], r["charged"], r["data"])
```

**MCP**

```json
{"name": "call_endpoint", "arguments": {"endpoint": "serper/google-maps-search", "body": {"q": "coffee in Bangalore"}}}
```

**Response**

```json
{
  "call_id": "c0a8e7a2-…",
  "endpoint": "serper/google-maps-search",
  "provider": "Serper",
  "status": "succeeded",
  "charged": { "credits": "9", "usd": "0.009" },
  "latency_ms": 840,
  "data": { "places": [ … ] }
}
```

## What you pay

- Each endpoint has one price per call for your plan (`price_per_call`); Pro, Scale and Max pay less than Pay as you go. Prices per plan are on [Prices](/prices#endpoints).
- The price is held before the call and charged when the provider answers. If it errors, refuses or times out (60 seconds), the hold is released and `refunded` shows it. When the provider reports a lower cost for the call, you pay the lower price.
- Calls count towards the agent's monthly budget, like purchases. Test keys (`sk_test_…`) check and price a call without making it.
- There's no pass rule here: a provider's "no results" is still an answer, and charged. For checked results use the verified jobs.
- Nothing you send or get back is stored. Your dashboard lists each call (endpoint, status, charge, latency) under Activity → Endpoint calls.

## On-request endpoints

Some endpoints act on resources held in a shared account (agent inboxes, phone agents, code sandboxes, browser sessions, page monitors, cloned voices), send messages or codes to people, or list everything in that account. One customer could then see or change another's, so these are listed but opened per customer: ask hello@arettic.com. Calling one returns `endpoint_on_request`.

## Errors

| Code | HTTP | When |
|---|---|---|
| [invalid_input](/docs/errors#invalid_input) | 400 | A missing `path_params` value, or `query`/`body` isn't an object. Nothing is held. |
| [unknown_endpoint](/docs/errors#unknown_endpoint) | 404 | No endpoint with that id. |
| [endpoint_on_request](/docs/errors#endpoint_on_request) | 409 | The endpoint is opened per customer. |
| [price_above_max](/docs/errors#price_above_max) | 402 | The price per call is above your `max_price`. |
| [over_budget](/docs/errors#over_budget) | 402 | The call would take the agent over its monthly budget. |
| [insufficient_credits](/docs/errors#insufficient_credits) | 402 | The balance can't cover the hold. |
| [endpoint_unavailable](/docs/errors#endpoint_unavailable) | 503 | The gateway is switched off. Retry later. |

Updated 2026-10-09. This page as HTML: https://arettic.com/docs/endpoints · Markdown: https://arettic.com/docs/endpoints.md · JSON: https://arettic.com/docs/endpoints.json