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

# API quickstart

Get your API key, make your first call, and understand how PredictHQ fits into a production integration.

## What you need

Before you start, you need:

1. A PredictHQ account - [log in](https://control.predicthq.com/) or [sign up for free](https://signup.predicthq.com/).
2. An API Key - create one in the next section.

## Create an API key

To create a key:

1. Log in to the [WebApp](https://control.predicthq.com/tokens).
2. Go to **API Tools → API Tokens**.
3. Click **Create Token**.
4. Enter a name.
5. Click **Create**.
6. Click **Copy Token**.
7. Store the token somewhere safe. The WebApp doesn't show it again.

In the `Authorization` header of every API request, use your API key:

```
Authorization: Bearer $API_TOKEN
```

## Make your first call

The Events API returns structured, deduplicated real-world events. To verify your API key is working and to explore what events look like in the response, run this request:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
        "Authorization": "Bearer $API_TOKEN",
        "Accept": "application/json"
    },
    params={
        "place.scope": "5128581",  # New York City
        "category": "concerts,sports,conferences",
        "active.gte": "2026-06-01",
        "active.lte": "2026-06-30",
        "limit": 10
    }
)

print(response.json())
```

{% hint style="info" %}
**Note:** The Events API is for discovery and explainability - understanding which events are happening and why they matter. For demand forecasting and ML, use the Features API instead. See [Which API Should I Use](/getting-started/core-concepts/which-api-should-i-use.md) for guidance on which API to use for your use case.
{% endhint %}

## How PredictHQ APIs work together

A single API call is not a production integration. PredictHQ designed its APIs to work as a pipeline:

1. **Saved Locations** - define your business locations once using `origin_geojson`. PredictHQ calculates Predicted Impact Area automatically and stores it against each location.
2. **Beam** - run a Beam Analysis per location using your historical demand data. Beam identifies which event categories actually drive demand at each location and returns an `analysis_id`.
3. **Features API** - call the Features API with your `analysis_id` to retrieve model-ready ML features, automatically scoped and filtered to your location.
4. **Events API** - use the Events API with your `analysis_id` to retrieve the specific events driving demand - for explainability and operational context.

The [Standard integration pattern](/integrations/integration-guides/standard-integration-pattern.md) shows the full recommended architecture, including refresh cadence and data storage patterns.

## What to do next

**I want to build a demand forecasting model** → Start with [Saved Locations](/api/saved-locations/overview.md), then run [Beam](/api/beam/overview.md), then call the [Features API](/api/features/get-features.md) with your `analysis_id`

**I want event-driven forecasts without building a model** → Go straight to the [Forecasts API](/api/forecasts/overview.md)

**I want to connect an AI assistant to PredictHQ** → Set up the [PredictHQ MCP server](/ai/mcp.md)

**I want to understand the full integration architecture** → Read the [Standard integration pattern](/integrations/integration-guides/standard-integration-pattern.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.predicthq.com/getting-started/api-quickstart.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.