> For the complete documentation index, see [llms.txt](https://docs.themochi.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.themochi.app/start-here/getting-started.md).

# Make your first API request

In this guide, you will ask Mochi for up to ten leads. This is a **read-only** request: it cannot add, change, or delete data.

## What you need

You need three things:

1. An **API key** issued by Mochi. The key identifies your integration and its organization. If you do not have one, ask your existing Mochi implementation or account contact.
2. The `leads:read` **scope**. A scope is a permission. This one allows the key to read leads.
3. A terminal on a trusted computer or server. Do not run this example in browser JavaScript, where visitors could see the key.

Mochi shows a new key only once. Save it in a server-side secret manager. Do not paste a real key into source code, documentation, screenshots, prompts, or support messages.

## Step 1: set the key for this terminal

Run the first command, paste the key when the cursor waits, and press Enter. The terminal does not display the key, and the key does not become part of the command in your shell history. The second command makes it available to cURL:

```bash
read -s MOCHI_API_KEY
export MOCHI_API_KEY
```

## Step 2: request up to ten leads

```bash
curl --fail --silent --show-error \
  --request GET \
  --url "https://api.themochi.app/v1/leads/?page_size=10" \
  --header "Authorization: Bearer ${MOCHI_API_KEY}" \
  --header "Accept: application/json"
```

## Step 3: confirm success

A successful response has this shape:

```json
{
  "data": [],
  "next_cursor": null
}
```

`data` is the list of leads. It may be empty when the organization has no leads. `next_cursor` tells you whether another page exists. You do not need it for this first request.

Your first request succeeded if cURL exits without an error and the response contains both fields. The request can return only leads from the organization linked to the key.

## If the first request fails

| Result | What to do                                                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `401`  | The key is missing, invalid, expired, or revoked. Check that the environment variable is set without printing its value. |
| `403`  | The key does not have `leads:read`. Ask for that permission instead of a broader key.                                    |
| `404`  | Check the base URL and path. The endpoint may not be enabled for your organization.                                      |
| `429`  | Wait for the number of seconds in the `Retry-After` response header, then try again.                                     |

For other failures, follow [Troubleshoot API requests](/troubleshooting-and-safety/diagnose-api-failures.md). Keep the `X-Request-ID` response header, but do not keep the key or response data in logs.

## Next steps

* Use the same request in [cURL, Python, Node.js/TypeScript, or PHP](/start-here/code-examples.md).
* Learn how to [load every page](/troubleshooting-and-safety/pagination.md).
* [Choose how to authenticate](/start-here/authentication.md) for a scheduled job, browser app, or AI tool.
* Follow [Test your integration safely](/troubleshooting-and-safety/testing-guide.md) before requesting write permissions.

Remove the temporary environment variable when you finish:

```bash
unset MOCHI_API_KEY
```