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

# 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.