---
title: "Getting Started"
description: "Create an API key, make your first call, and learn the conventions every endpoint shares."
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt)

## Quick Start

### 1. Create an Account

Sign up at [apinoa.com](https://apinoa.com) and verify your email address. No card is needed.

### 2. Add Credit

Calls are billed from a prepaid balance at [the rate on the pricing page](/pricing); there are no plans
to choose. **Dashboard > Balance** shows what is left and tops it up. To evaluate first, request free
credit from the Free Credit card on your dashboard: up to **$1** per account in total, including the
$0.10 from step 3.

### 3. Create an API Key

The quickest way is from your terminal. Run this in your project directory:

```bash
npx apinoa-mcp login
```

It opens a page where you sign in to apinoa (or create an account), enter the code it shows and approve.
The key is then written to `.env` as `APINOA_API_KEY`. An account's first key made this way, or by signing
in to the [hosted MCP server](/docs/sdks#hosted-nothing-to-install), comes with **$0.10 of evaluation
credit**, once per account. [Authentication](/docs/authentication#get-a-key) has the details.

Or go to **Dashboard > API keys** and create a key. It is shown **once**, at creation, so store it right away:

```bash
export APINOA_API_KEY="myapp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

One key works for every API. The examples in these docs read it from the `APINOA_API_KEY` environment
variable: `export` it as above, or load the `.env` that `npx apinoa-mcp login` wrote.

### 4. Make Your First Call

```bash tab="cURL"
curl "https://gateway.apinoa.com/v1/walmart/search?query=wool+socks" \
  -H "x-api-key: $APINOA_API_KEY"
```

```js tab="JavaScript"
const params = new URLSearchParams({ query: "wool socks" });
const res = await fetch(`https://gateway.apinoa.com/v1/walmart/search?${params}`, {
  headers: { "x-api-key": process.env.APINOA_API_KEY },
});
const { success, data, error } = await res.json();
console.log(success ? data.items[0] : error);
```

```python tab="Python"
import os

import requests

res = requests.get(
    "https://gateway.apinoa.com/v1/walmart/search",
    params={"query": "wool socks"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
body = res.json()
print(body["data"]["items"][0] if body["success"] else body["error"])
```

```ts tab="TypeScript SDK"
import { ApinoaClient } from "@apinoa/sdk"; // npm install @apinoa/sdk

const apinoa = new ApinoaClient(); // reads APINOA_API_KEY
const { data } = await apinoa.walmart.search({ query: "wool socks" });
console.log(data.items[0]);
```

```python tab="Python SDK"
from apinoa import Apinoa  # pip install apinoa

client = Apinoa()  # reads APINOA_API_KEY
res = client.walmart.search(query="wool socks")
print(res.data.items[0])
```

The [SDKs](/docs/sdks) wrap every operation, and the [MCP server](/docs/sdks#mcp-server) gives Claude Code,
Codex and Cursor the whole API.

### 5. Read the Response

Every response has `success`, then `data` (or `error`). A search returns a
[`SearchResult`](/docs/api-reference/marketplaces/response-schema#searchresult); shortened, it looks like this:

```json
{
  "success": true,
  "data": {
    "marketplace": "walmart",
    "query": "wool socks",
    "page": { "index": 1, "size": 47, "total": 4871 },
    "items": [
      {
        "marketplace": "walmart",
        "id": "344144554",
        "title": "Genuine Dickies Men's Wool Thermal Crew Sock, 3 Pack, Shoe Size 6-12",
        "price": { "currency": "USD", "amount": 15.98 },
        "rating": { "average": 4.7, "count": 551 },
        "inStock": true
      }
    ]
  }
}
```

### 6. Switch Platforms

The platform is a segment of the path. The key, the parameter names and the response shape stay the same:

```bash
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"
curl "https://gateway.apinoa.com/v1/shopify/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"
```

## Conventions

These hold for every endpoint in these docs.

### Base URL

```
https://gateway.apinoa.com/v1/{platform}/{operation}
```

`{platform}` is a marketplace (`amazon`, `walmart`, `shopify`, `tiktokshop`, `aliexpress`), a social platform
(`tiktok`, `instagram`, `youtube`, `reddit`, `x`, `threads`, `linkedin`), a search engine (`google`, `bing`,
`naver` and [the others](/docs/api-reference/serp)) or an AI answer engine (`chatgpt`, `gemini`, `google-aio`,
`google-ai-mode`, `naver-ai-brief`, `naver-ai-tab`). `{operation}` is lowercase, with words joined by hyphens
(`image-search`). [`GET /v1/marketplaces`](https://gateway.apinoa.com/v1/marketplaces) lists every platform
and operation.

### GET or POST

Every operation accepts its parameters either as a query string with `GET` or as a JSON body with `POST`;
the two are equivalent. The exceptions are image search, which is `POST` only because an image does not fit
in a URL, and AI answers, which take their inputs as a JSON body.

```bash
curl -X POST "https://gateway.apinoa.com/v1/walmart/search" \
  -H "x-api-key: $APINOA_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query": "wool socks", "priceMax": 30}'
```

An unknown parameter is a `400` that names it, never silently ignored.

### The Envelope

Every response is JSON with `success`, then either `data` or `error`:

```json
{
  "success": false,
  "error": { "code": "INVALID_PARAMS", "message": "(root): Unrecognized key(s) in object: 'nope'" },
  "requestId": "8d76f93c85cc4e9f911e2d0de23334c4"
}
```

`error.code` is stable and documented in [Errors](/docs/errors); `error.message` is for people. Quote the
`requestId` (also sent as the `x-request-id` header) if you contact support.

### Response Headers

| Header | Meaning |
|---|---|
| `x-request-id` | The request's id, the same as `requestId` in an error body |
| `x-apinoa-cost` | The units this call was billed |
| `x-api-version` | The API version that answered (`v1`) |

### Absent Means Unknown

A field the platform did not state is **left out**, never filled with a default. An absent `price` is not
zero, and an absent `metrics.likes` is a hidden count, not zero likes. Prices are decimal amounts in major
units (`12.97`), with their currency. Times are ISO 8601, in UTC.

### Paging

A list answers with a page. Depending on the operation, ask for the next one with:

- **`page`** — a 1-based page number, on operations that page by number (most marketplace searches).
- **`cursor`** — the `cursor` the previous page returned, on operations that page by cursor (Shopify, every
  SNS list). Pass it on its own; it carries everything the first call asked for. No `cursor` in a response
  means there is no next page.

Each endpoint's Parameters table shows which one it takes.

### Pricing

Each call is billed in **units** at its API's unit price: [Pricing](/pricing) lists every API's price, and
each endpoint's page states what one call costs. The rate steps down above 1,000 calls a day. Most calls
cost one unit; each endpoint's Pricing section says when one can cost more. A call that fails is not billed.

## Next Steps

- [Marketplace API](/docs/api-reference/marketplaces): the shared operations and which marketplace has which
- [SNS API](/docs/api-reference/sns): the eight shared operations across seven platforms
- [SERP API](/docs/api-reference/serp): search results pages from 16 search engines in one schema
- [AI Answers API](/docs/api-reference/answers): what ChatGPT, Gemini, Google and Naver's AI answer to a prompt
- [SDKs and MCP](/docs/sdks): TypeScript, Python, the MCP server and the OpenAPI document
- [Image Translate](/docs/api-reference/image-translate): translate the text inside product images
- [Authentication](/docs/authentication): sending and protecting your key
- [Errors](/docs/errors): every error code and what to do about it