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

# Getting started

How to access the Horizon API from an embedded experience

To get started with the Horizon API, first follow the steps for [Embedding Horizon](https://docs.horizon.ipaper.io/horizon-experience/embedding-horizon.md) to embed a Horizon experience into your webpage. You will then be able to access the API for that experience.

The embedded web component will emit a `ready` event when it's done loading and a `ready` attribute will also be added to the element. To ensure everything is ready, check both the `ready` attribute and `await` the `ready` event:

```html
<ip-embed-leaflet id="horizon" alias="[ACCOUNT_NAME]/[ALIAS]"></ip-embed-leaflet>

<script>
  function whenHorizonReady(horizonEl) {
    // Resolve immediately if the element is already ready
    if (horizonEl.getAttribute('ready') === 'true') return Promise.resolve(true);
    // Otherwise, wait for the ready event
    return new Promise((resolve) => {
      horizonEl.addEventListener('ready', () => resolve(true), { once: true });
    });
  }
  
  const horizonElement = document.getElementById('horizon');
  whenHorizonReady(horizonElement).then(() => {
    // Your code
  });
</script>
```

{% hint style="warning" %}
If you have previously embedded Horizon on your page(s), the custom tag used on the page may be `<ip-embed>` instead of `<ip-embed-leaflet>`.&#x20;

`<ip-embed>` is still supported, but we recommend updating to `<ip-embed-leaflet>` at your earliest convenience.&#x20;
{% endhint %}

When the Horizon experience is ready, you can get the API:

```javascript
whenHorizonReady(horizonElement).then(async () => {
    const api = await horizonElement.getApi();
    // Your code
});
```

***

Alternatively, you can use a window bound function as a callback for the `ready` event:

```html
<ip-embed-leaflet alias="[ACCOUNT_NAME]/[ALIAS]" on-ready="onHorizonReady"></ip-embed-leaflet>

<script>
  window.onHorizonReady = (horizonEl, api) => {
    // Your code
  };
</script>
```


---

# 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.horizon.ipaper.io/horizon-api/getting-started.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.
