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

# Get Started with Feather in Under 5 Minutes

> Make your first Feather API call, create an agent, and run a conversation end-to-end in just a few steps.

Get up and running with Feather in minutes. This guide walks you through creating an API key, spinning up your first agent, and running a conversation end-to-end — no SDKs or dashboards required, just straightforward HTTP requests.

<Note>
  You need a Feather account and your **organization ID** before you begin. All
  requests in this guide target the sandbox environment at
  `https://api-sandbox.featherhq.com`. Contact Feather to provision production
  credentials.
</Note>

<Steps>
  <Step title="Create an API key">
    Every request to the Feather API must include a valid API key. Create one now by posting to `/v1/identity/api-keys` — you can name it anything that helps you remember what it is for.

    <CodeGroup>
      ```bash Create API Key theme={null}
      curl -X POST https://api-sandbox.featherhq.com/v1/identity/api-keys \
        -H 'Content-Type: application/json' \
        -H 'x-api-key: <your-bootstrap-or-org-token>' \
        -d '{"name": "quickstart"}'
      ```
    </CodeGroup>

    ```json Response (201 Created) theme={null}
    {
      "id": "ak_01hwqz3k9fmxp7v2brgnte8cja",
      "name": "quickstart",
      "plain_text_key": "fth_live_4T8zQrVnLwJpKsYdXcMbUeAoHiFgNt",
      "key_prefix": "fth_live_4T8z",
      "scopes": [],
      "is_active": true,
      "last_used_at": null,
      "expires_at": null,
      "created_at": "2025-01-15T10:32:00Z"
    }
    ```

    <Warning>
      Copy the `plain_text_key` value now and store it in your environment or
      secrets manager. Feather returns it **only once** and never exposes the
      full key again.
    </Warning>

    For the rest of this guide, replace `<your-key>` in every command with the `plain_text_key` value you just copied.
  </Step>

  <Step title="Verify your identity">
    Confirm your key works and check which organization and role it belongs to by calling `GET /v1/identity/whoami`.

    <CodeGroup>
      ```bash Verify Identity theme={null}
      curl https://api-sandbox.featherhq.com/v1/identity/whoami \
        -H 'x-api-key: <your-key>'
      ```
    </CodeGroup>

    ```json Response (200 OK) theme={null}
    {
      "id": "usr_01hvbp4nrtemk6wjq8xcgdfy2s",
      "email": "you@example.com",
      "role": "admin",
      "organization_id": "org_01hv3qxmpkyndzcwbt8fj6r90e",
      "kb_clearance_level": 3,
      "created_at": "2025-01-01T09:00:00Z"
    }
    ```

    Note your `organization_id` — you will need it when configuring agents and conversations in later steps.

    <Tip>
      `kb_clearance_level` controls which knowledge-base documents your key can
      retrieve. A higher number means access to more sensitive content tiers. See
      the [Knowledge Bases](/concepts/knowledge-bases) concept page for details.
    </Tip>
  </Step>

  <Step title="Create an agent">
    An agent is the AI brain behind your conversations. Create your first one by posting a name and description. Feather provisions the agent, creates an initial revision, and returns the IDs you need to start conversations.

    <CodeGroup>
      ```bash Create Agent theme={null}
      curl -X POST https://api-sandbox.featherhq.com/v1/agents \
        -H 'x-api-key: <your-key>' \
        -H 'Content-Type: application/json' \
        -d '{
          "name": "Support Bot",
          "description": "Answers customer questions about our product."
        }'
      ```
    </CodeGroup>

    ```json Response (201 Created) theme={null}
    {
      "id": "agt_01hx2rp7tqkwn5cbms0evuy4dj",
      "name": "Support Bot",
      "description": "Answers customer questions about our product.",
      "active_revision_id": "rev_01hx2rp7vznlm8fbqt9gscwo3k",
      "is_active": true,
      "created_at": "2025-01-15T10:35:00Z",
      "updated_at": "2025-01-15T10:35:00Z"
    }
    ```

    Save the agent `id` — you'll use it as the `assistant_id` when you start a conversation in the next step.
  </Step>

  <Step title="Start a conversation">
    Open a new conversation session by posting to `/v1/v2/conversations`. Set `channel` to `"api"` for a programmatic session, and use `session_type: "test"` while you're developing so the session is flagged as non-production in your analytics.

    <CodeGroup>
      ```bash Start Conversation theme={null}
      curl -X POST https://api-sandbox.featherhq.com/v1/v2/conversations \
        -H 'x-api-key: <your-key>' \
        -H 'Content-Type: application/json' \
        -d '{
          "end_user_id": "usr_01hvbp4nrtemk6wjq8xcgdfy2s",
          "channel": "api",
          "assistant_id": "agt_01hx2rp7tqkwn5cbms0evuy4dj",
          "session_type": "test"
        }'
      ```
    </CodeGroup>

    ```json Response (201 Created) theme={null}
    {
      "id": "ses_01hxkqm3pj7ftv9rbew5cydnug",
      "end_user_id": "usr_01hvbp4nrtemk6wjq8xcgdfy2s",
      "channel": "api",
      "assistant_id": "agt_01hx2rp7tqkwn5cbms0evuy4dj",
      "session_type": "test",
      "status": "active",
      "created_at": "2025-01-15T10:36:00Z"
    }
    ```

    Copy the conversation `id` — you'll need it to send messages in the next step.
  </Step>

  <Step title="Send a message">
    Send the first user message by posting a turn to your conversation. Feather runs the message through your agent and returns the assistant's reply along with the updated session status.

    <CodeGroup>
      ```bash Send a Message theme={null}
      curl -X POST https://api-sandbox.featherhq.com/v1/v2/conversations/ses_01hxkqm3pj7ftv9rbew5cydnug/turns \
        -H 'x-api-key: <your-key>' \
        -H 'Content-Type: application/json' \
        -d '{
          "user_message": "Hello, can you help me?"
        }'
      ```
    </CodeGroup>

    ```json Response (200 OK) theme={null}
    {
      "turn_id": "trn_01hxkqn8sv2gep0qmzr7byft4c",
      "user_message": "Hello, can you help me?",
      "text": "Hi there! Absolutely — I'm Support Bot, and I'm here to help. What can I assist you with today?",
      "session_status": "active",
      "created_at": "2025-01-15T10:36:05Z"
    }
    ```

    You've just run your first end-to-end Feather conversation. The `session_status` field stays `"active"` while the conversation is ongoing. It transitions to `"completed"` or `"handed_off"` based on your agent's policies.
  </Step>
</Steps>

***

## Next Steps

Now that you have a working agent and conversation, explore what else Feather can do.

<CardGroup cols={2}>
  <Card title="Add a Knowledge Base" icon="database" href="/concepts/agents">
    Connect a knowledge base to your agent so it can answer questions grounded in your own documents and data.
  </Card>

  <Card title="Ingest Your Docs" icon="file-import" href="/guides/ingest-documents">
    Upload files, crawl URLs, or sync from Notion and Google Drive to populate your knowledge base.
  </Card>

  <Card title="Stream Responses" icon="bolt" href="/api-reference/runtime-v2/run-one-v2-conversation-turn-with-an-sse-response">
    Use the streaming turns endpoint to deliver low-latency, token-by-token replies to your users.
  </Card>

  <Card title="Evaluate Quality" icon="chart-bar" href="/guides/evaluations">
    Run simulation suites and model-judge evaluators to measure and continuously improve agent performance.
  </Card>
</CardGroup>