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

# Get Started with VyomFlow API

> Make your first VyomFlow API request against production: create a chat, send a message, stream the response, and check your credit balance.

Every step below is copy-pasteable against the real production API at `https://api.vyomflow.co.in`. You only need an API key.

<Steps>
  <Step title="Mint an API key">
    Sign in to [www.vyomflow.co.in](https://www.vyomflow.co.in) and open **Settings → API Keys** (`/settings/api-keys`). Create a key with at least `chats:write`, `chats:read`, `runs:write`, `runs:read`, `waitpoints:respond`, and `credits:read`. Export it:

    ```bash theme={null}
    export VYOMFLOW_API_KEY="<your-api-key>"
    ```

    See [Authentication](/authentication) for scopes and key lifecycle.
  </Step>

  <Step title="Create a chat">
    <CodeGroup>
      ```bash curl theme={null}
      curl -s -X POST https://api.vyomflow.co.in/api/public/v1/chats \
        -H "Authorization: Bearer $VYOMFLOW_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"title": "My first chat"}'
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch("https://api.vyomflow.co.in/api/public/v1/chats", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.VYOMFLOW_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ title: "My first chat" }),
      });
      const chat = await res.json();
      console.log(chat);
      ```
    </CodeGroup>

    Example response (`201`):

    ```json theme={null}
    {
      "id": "chat_01JXYZ1234567890ABCDEF",
      "title": "My first chat",
      "pinnedAt": null,
      "createdAt": "2026-08-27T10:00:00.000Z",
      "updatedAt": "2026-08-27T10:00:00.000Z",
      "activeRunId": null
    }
    ```

    Save `id` as `$CHAT_ID` — you'll use it in every subsequent call.
  </Step>

  <Step title="Send a message">
    <CodeGroup>
      ```bash curl theme={null}
      curl -s -X POST https://api.vyomflow.co.in/api/public/v1/chats/$CHAT_ID/messages \
        -H "Authorization: Bearer $VYOMFLOW_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"content": [{"type": "text", "text": "Hello, agent!"}]}'
      ```

      ```javascript JavaScript theme={null}
      const messageRes = await fetch(
        `https://api.vyomflow.co.in/api/public/v1/chats/${chat.id}/messages`,
        {
          method: "POST",
          headers: {
            Authorization: `Bearer ${process.env.VYOMFLOW_API_KEY}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ content: [{ type: "text", text: "Hello, agent!" }] }),
        },
      );
      const turn = await messageRes.json();
      console.log(turn);
      ```
    </CodeGroup>

    Example response (`201`):

    ```json theme={null}
    {
      "chatId": "chat_01JXYZ1234567890ABCDEF",
      "message": {
        "id": "msg_01JXYZ0987654321FEDCBA",
        "chatId": "chat_01JXYZ1234567890ABCDEF",
        "role": "user",
        "content": [{ "type": "text", "text": "Hello, agent!" }],
        "status": "complete",
        "createdAt": "2026-08-27T10:01:00.000Z"
      },
      "run": {
        "id": "run_01JXYZABCDEF1234567890",
        "chatId": "chat_01JXYZ1234567890ABCDEF",
        "status": "queued",
        "userMessageId": "msg_01JXYZ0987654321FEDCBA",
        "assistantMessageId": null,
        "lastStreamIndex": -1,
        "requestedModel": "openrouter/free",
        "createdAt": "2026-08-27T10:01:00.000Z"
      },
      "stream": {
        "url": "https://api.vyomflow.co.in/api/public/v1/runs/run_01JXYZABCDEF1234567890/stream",
        "fromIndex": 0
      }
    }
    ```

    An optional `Idempotency-Key` header on this request makes a retried POST replay the original turn instead of sending a duplicate message and charging credits twice.

    Save `run.id` as `$RUN_ID`. The `stream.url` is where you consume live output.
  </Step>

  <Step title="Stream the response">
    Open the SSE stream with `Authorization` as a header (never a query parameter — `EventSource` can't send custom headers, so use `fetch` or a header-capable SSE client):

    ```bash theme={null}
    curl -N --http1.1 \
      -H "Authorization: Bearer $VYOMFLOW_API_KEY" \
      https://api.vyomflow.co.in/api/public/v1/runs/$RUN_ID/stream
    ```

    You'll see events like `run.status`, `message.delta`, `tool.status`, and eventually a terminal `run.completed`/`run.failed`/`run.cancelled` event that closes the stream. Full event reference: [Streaming](/streaming).
  </Step>

  <Step title="Answer a waitpoint, if one appears">
    Some turns pause on a `waitpoint.created` event — most commonly a `CREDIT_APPROVAL` waitpoint before an expensive tool call. Answer it to resume the run:

    ```bash theme={null}
    curl -s -X POST https://api.vyomflow.co.in/api/public/v1/waitpoints/$WAITPOINT_ID/respond \
      -H "Authorization: Bearer $VYOMFLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"kind": "CREDIT_APPROVAL", "approved": true}'
    ```

    If no waitpoint appears, skip this step — most turns complete without one.
  </Step>

  <Step title="Check the run's final state">
    ```bash theme={null}
    curl -s https://api.vyomflow.co.in/api/public/v1/runs/$RUN_ID \
      -H "Authorization: Bearer $VYOMFLOW_API_KEY"
    ```

    This is the REST recovery path — useful if your stream connection dropped, or just to confirm the run's terminal `status` and `totalCreditsUsed` after the fact.
  </Step>

  <Step title="Check your credit balance">
    ```bash theme={null}
    curl -s https://api.vyomflow.co.in/api/public/v1/me/credits \
      -H "Authorization: Bearer $VYOMFLOW_API_KEY"
    ```

    ```json theme={null}
    {
      "balance": "97.5000",
      "held": "0.0000",
      "available": "97.5000"
    }
    ```

    Balances cross the wire as strings, not numbers, so a client never rounds a money value through a float.
  </Step>
</Steps>

## Next steps

<CardGroup cols={3}>
  <Card title="Authentication" href="/authentication">
    API keys, scopes, and the security model.
  </Card>

  <Card title="Streaming" href="/streaming">
    The full SSE event reference and reconnect protocol.
  </Card>

  <Card title="MCP" href="/mcp">
    Connect an MCP client like Claude Code directly to VyomFlow.
  </Card>
</CardGroup>