> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickshealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create your first run and read its transcript in about five minutes.

To follow this quickstart, you need a Clicks account with a configured agent, that agent's
template ID (shown on its **API access** tab), and `curl` or Python with the `requests` library.

The code samples on this page use the base URL `https://app.clickshealth.com/api/orchestrator/v1`.

<Steps>
  <Step title="Mint an API key">
    In the Clicks app, open **Agents → your agent → API access → Create key**. Clicks
    shows the full key (`ak_…`) only once, so copy it and store it in a secret manager.
    You can't retrieve the key later. If you lose it, create a new one.

    ```bash shell theme={null}
    export CLICKS_API_KEY="ak_..."
    ```
  </Step>

  <Step title="Create an agent run">
    Set `template_id` to the ID of the agent the key belongs to. The key determines which
    agent runs; the field is only a cross-check. You can find the ID at the top of the same
    **API access** tab.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://app.clickshealth.com/api/orchestrator/v1/agents \
        -H "Authorization: Bearer $CLICKS_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "My first run",
          "template_id": "<your-agent-template-id>",
          "input_text": "Summarize the latest AI news in three bullet points."
        }'
      ```

      ```python Python theme={null}
      import os, requests

      resp = requests.post(
          "https://app.clickshealth.com/api/orchestrator/v1/agents",
          headers={"Authorization": f"Bearer {os.environ['CLICKS_API_KEY']}"},
          json={
              "name": "My first run",
              "template_id": "<your-agent-template-id>",
              "input_text": "Summarize the latest AI news in three bullet points.",
          },
      )
      resp.raise_for_status()
      agent_id = resp.json()["agent_id"]
      print(agent_id)
      ```
    </CodeGroup>

    The response is `201` with only the run's ID. Because execution is asynchronous,
    everything else comes from polling:

    ```json 201 Created theme={null}
    {
      "agent_id": "0f4d3f9a-6b1c-4a2e-8c7d-5e9b0a1f2c3d"
    }
    ```
  </Step>

  <Step title="Poll until it finishes">
    Poll every few seconds while `loop_status` is `running`. Runs commonly take several
    minutes. For the status values and backoff guidance, see
    [Agent lifecycle and polling](/agent-lifecycle).

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://app.clickshealth.com/api/orchestrator/v1/agents/$AGENT_ID \
        -H "Authorization: Bearer $CLICKS_API_KEY"
      ```

      ```python Python theme={null}
      import os, time, requests

      BASE = "https://app.clickshealth.com/api/orchestrator/v1"
      HEADERS = {"Authorization": f"Bearer {os.environ['CLICKS_API_KEY']}"}

      def wait_until_done(agent_id: str) -> dict:
          while True:
              resp = requests.get(f"{BASE}/agents/{agent_id}", headers=HEADERS)
              resp.raise_for_status()
              run = resp.json()
              if run["loop_status"] != "running":
                  return run
              time.sleep(5)

      run = wait_until_done(agent_id)
      for message in run["transcript"]:
          print(f"[{message['role']}] {message['text']}")
      ```
    </CodeGroup>
  </Step>

  <Step title="Read the transcript">
    The transcript includes only the inputs the agent accepted and each turn's final output.
    It doesn't include intermediate tool steps. An empty transcript early in a run is normal.
  </Step>
</Steps>

<Warning>
  **Always send input\_text.** Without it, the API creates the run but never starts a turn:
  `loop_status` stays `running` until someone provides input in the Clicks app.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.