# Quickstart

| `NONE` \| `ON_START` \| `ON_TOOL_CALL` (defaults to `NONE`). |
| ------------------------------------------------------------ |

{% hint style="info" %}
Check out the [Mental Model](/basics/mental-model.md) and [Core Objects](/basics/core-objects.md) to make your life easier
{% endhint %}

### Prerequisites

* **API key** with access to your workspace (`x-api-key`).
* At least **one integration enabled** (managed or custom). For first runs, prefer a managed and read-only integration.
* OpenAPI spec is downloadable [here](https://openapi.gitbook.com/o/35ZmqYj6yWUW4rLOFJSa/spec/toolregistry-api.json).

### Enable an integration

1. Go to [integrations](https://app.toolregistry.ai/integrations) 
2.  Enable an integration (or upload a custom integration) - For this demo we recommend "Google Calendar" or "Outlook Calendar"

<figure><img src="/files/cMyP9pwvU60Vf7juvxbI" alt=""><figcaption></figcaption></figure>

### Get your API key

1. Head over to [API keys section](https://app.toolregistry.ai/api-keys) in console&#x20;

   <figure><img src="/files/gnOC4LEXPievUP8Fy390" alt=""><figcaption></figcaption></figure>

2. Generate an API key

<figure><img src="/files/7MSLoJhbK5bMAC1u6znO" alt=""><figcaption></figcaption></figure>

3. Copy and Save the API key

<figure><img src="/files/H0uh2Btqj8QZeCPxYjdW" alt=""><figcaption></figcaption></figure>

3. Export the api Key

```sh
export TR_API_KEY="sk_live_..."  
export TR_API_URL="https://api.toolregistry.ai"
```

### Create your first Run

A **Run** is the execution of an intent with guardrails.

**Request Fields**

<table><thead><tr><th width="265.17578125">Field</th><th>Type</th><th width="116.26171875">Required</th><th>Notes</th></tr></thead><tbody><tr><td>intent</td><td>String</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td>What outcome you want (natural language).</td></tr><tr><td>context</td><td>String</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td>Hidden, technical details (timezone, constraints). Keep sensitive data here; don’t show to end users.</td></tr><tr><td>userId</td><td>String</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td>Identity whose tokens/permissions apply (act‑as‑user).</td></tr><tr><td>selectedCustomerIntegrationIds</td><td>string[]</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td>Allow‑list of connections, or <code>["*"]</code> for all active.</td></tr><tr><td>approvalStrategy</td><td>enum</td><td>-</td><td><code>NONE</code> | <code>ON_START</code> | <code>ON_TOOL_CALL</code> (defaults to <code>NONE</code>).</td></tr><tr><td>outputSchema</td><td>object</td><td>-</td><td>Define the expected output format by providing JSON Schema Draft-07 object</td></tr></tbody></table>

Example intent (declarative, long‑form)

{% code overflow="wrap" %}

```
Book a meeting in Google or Outlook calendar for next thursday at 12:00 - Name "Lunch  with myself without a screen".
```

{% endcode %}

### Create the run (cURL):

```sh
RUN_PAYLOAD='{
"intent": "Book a meeting in Google or Outlook calendar for next thursday at 12:00 - Name "Lunch  with myself without a screen",
"context": "timezone=Europe/Copenhagen; window=next_week; one_per_day=true; stage=Proposal Made; staleness_days=14; meeting_time=12:00; slack_channel=#demo-update",
"userId": "user-123",
"selectedCustomerIntegrationIds": ["*"]
}'


curl -s -X POST "$TR_API_URL/v1/runs" \
-H "x-api-key: $TR_API_KEY" \
-H "Content-Type: application/json" \
-d "$RUN_PAYLOAD"
```

### Watch the live execution

```sh
RUN_ID="<uuid-from-create>"
curl -N -H "x-api-key: $TR_API_KEY" \
"$TR_API_URL/v1/runs/$RUN_ID/sse"
```

### Inspect the Run and result

```
curl -s -H "x-api-key: $TR_API_KEY" \
"$TR_API_URL/v1/runs/$RUN_ID" | jq
```

### Production tips

* **Intent**: be outcome-focused and testable. Prefer declarative language (what), let the system decide (how).
* **Context**: keep sensitive details here; do not surface to end users.
* **Approvals**: start with `ON_TOOL_CALL` for writes for your agent; `ON_START` if you need human to review the plan.
* **Least privilege**: choose a `userId` with only the permissions needed.
* **Scoping**: For QuickStart user \["\*"] for integrations to select all that have been enabled
* **Observability**: use SSE in staging/early prod to watch real behavior.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toolregistry.ai/getting-started/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.