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

# Quickstart

> Spawn your first Rose agent in 5 minutes

## 1. Get Your API Key

1. Subscribe to Rose Labs at [roselabs.ai](https://roselabs.ai)
2. Navigate to **Settings > API Keys**
3. Copy your API key

## 2. Create an Agent

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://navi-j9a9.onrender.com/api/agents" \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "goal": "Find the current price of Bitcoin and Ethereum",
      "model": "rose-1-lite"
    }'
  ```

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

  response = requests.post(
      "https://navi-j9a9.onrender.com/api/agents",
      headers={
          "Content-Type": "application/json",
          "x-api-key": "YOUR_API_KEY"
      },
      json={
          "goal": "Find the current price of Bitcoin and Ethereum",
          "model": "rose-1-lite"
      }
  )
  agent = response.json()
  print(f"Agent ID: {agent['agent_id']}")
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://navi-j9a9.onrender.com/api/agents",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
      },
      body: JSON.stringify({
        goal: "Find the current price of Bitcoin and Ethereum",
        model: "rose-1-lite"
      })
    }
  );
  const agent = await response.json();
  console.log(`Agent ID: ${agent.agent_id}`);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "goal": "Find the current price of Bitcoin and Ethereum",
  "model": "rose-1-lite",
  "status": "ACTIVE",
  "progress": 0,
  "created_at": "2024-01-15T10:30:00Z"
}
```

## 3. Poll for Results

Agents work asynchronously. Poll the status endpoint to check progress and retrieve messages.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://navi-j9a9.onrender.com/api/agents/550e8400-e29b-41d4-a716-446655440000" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import time

  agent_id = "550e8400-e29b-41d4-a716-446655440000"

  while True:
      response = requests.get(
          f"https://navi-j9a9.onrender.com/api/agents/{agent_id}",
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      status = response.json()

      print(f"Status: {status['agent']['status']}, Progress: {status['agent']['progress']:.0%}")

      if status["agent"]["status"] in ["COMPLETED", "FAILED"]:
          break

      time.sleep(2)

  # Print final messages
  for msg in status["messages"]:
      print(f"[{msg['role']}] {msg['text'][:200]}")
  ```

  ```typescript TypeScript theme={null}
  const agentId = "550e8400-e29b-41d4-a716-446655440000";

  const pollAgent = async () => {
    while (true) {
      const response = await fetch(
        `https://navi-j9a9.onrender.com/api/agents/${agentId}`,
        { headers: { "x-api-key": "YOUR_API_KEY" } }
      );
      const status = await response.json();

      console.log(`Status: ${status.agent.status}, Progress: ${Math.round(status.agent.progress * 100)}%`);

      if (["COMPLETED", "FAILED"].includes(status.agent.status)) {
        return status;
      }

      await new Promise(r => setTimeout(r, 2000));
    }
  };

  const result = await pollAgent();
  result.messages.forEach(msg => console.log(`[${msg.role}] ${msg.text}`));
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "agent": {
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "progress": 1.0,
    "token_count": 1520,
    "message_count": 4
  },
  "messages": [
    {
      "role": "USER",
      "text": "Find the current price of Bitcoin and Ethereum"
    },
    {
      "role": "ASSISTANT",
      "text": "I'll search for the current cryptocurrency prices..."
    },
    {
      "role": "ASSISTANT",
      "text": "Current prices:\n- Bitcoin: $97,432\n- Ethereum: $3,891"
    }
  ]
}
```

## 4. Choose Your Model

| Model          | Best For                             | Cost           |
| -------------- | ------------------------------------ | -------------- |
| `rose-1-lite`  | Fast tasks, simple research          | Lower cost     |
| `rose-1-ultra` | Complex reasoning, detailed analysis | Higher quality |

See [Models](/api-reference/models) for detailed pricing.

## Next Steps

* [Authentication](/authentication) - API key management
* [Agents API](/api-reference/agents) - Full API reference (pause, resume, delete)
* [Error Handling](/api-reference/errors) - Handle errors gracefully