# Frequently asked questions

## General

### What is the API base URL?

```
https://api.forms.app
```

### Which forms are returned when I list my account?

The list includes all forms that belong to your authenticated account, regardless of visibility (`public`, `unlisted`, or `private`), as long as they are not in the trash or archived.

## Authentication

### Should I use an API key or OAuth?

- **API key**: best for server-side scripts, cron jobs, and backend integrations you control.
- **OAuth bearer token**: best when a third-party app needs access on behalf of a user.


For most getting-started scenarios, an API key is enough.

### Can I use both an API key and a bearer token in one request?

No. The API requires exactly one authentication method per request. Sending both returns `401 Unauthorized`.

### I lost my API key. Can I retrieve it?

No. Keys are shown only once at creation. Revoke the old key in **Account Settings → API Keys** and create a new one.

### How many API keys can I create?

You can create multiple keys (for example, one per environment or integration) and revoke any of them individually.

## Responses and errors

### What does the response envelope look like?

Every response wraps the payload in a consistent structure. On success, `success` is `true` and the payload is in `data`. On failure, `success` is `false`, `data` is `null`, and details are in `errors`. See [The essentials](/guides/the-essentials#response-envelope).

### How do I handle errors in code?

1. Check the HTTP status code.
2. Parse the JSON body.
3. If `success` is `false`, read the `errors` array for `errorCode` and `errorMessage`.


### Why am I getting `404 Not Found` for a form?

The form may not exist, or it may belong to a different account. Confirm you are using the correct `_id` from `GET /v1/form` and the same credentials that own the form.

## Submissions

### How does pagination work for submissions?

Answers are returned in pages. Start with `pageNumber: 1`, then increment for each subsequent page. Compare the number of records you have collected against `totalCount` in the response to know when you are done. See [Fetching submissions](/guides/tutorials/fetching-submissions).

### What is `searchAfter` in the answer response?

Each page includes a `searchAfter` cursor pointing to the last record on that page. For most integrations, incrementing `pageNumber` is enough. The cursor is available for advanced cursor-based navigation.

## Rate limits

### What happens when I hit the rate limit?

The API returns `429 Too Many Requests`. Wait briefly and retry. Avoid hammering the endpoint in a tight loop.

### Is there a health check endpoint?

Yes. `GET /__health` returns the gateway status and does not require authentication. Use it for uptime monitoring.

## Getting help

- [Quick start](/guides/quickstart): create a key and make your first call
- [API reference](/apis): endpoints, schemas, and examples
- [forms.app support](https://forms.app/en/help-center): account and product questions