Get Started with Feather in Under 5 Minutes

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

You need a Feather account before you begin. All requests in this guide target the sandbox environment at https://api-sandbox.featherhq.com. Contact Feather to provision production credentials.

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.

Create API Key

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"}'

Response (201 Created)

{
  "id": "ak_01hwqz3k9fmxp7v2brgnte8cja",
  "name": "quickstart",
  "plain_text_key": "fth_live_4T8zQrVnLwJpKsYdXcMbUeAoHiFgNt",
  "key_prefix": "fth_live_4T8z",
  "scopes": [],
  "is_active": true,
  "expires_at": null,
  "created_at": "2026-01-15T10:32:00Z"
}

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.

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

Verify your identity

Confirm your key works and check which organization and role it belongs to by calling GET /v1/identity/whoami.

Verify Identity

curl https://api-sandbox.featherhq.com/v1/identity/whoami \
  -H 'x-api-key: <your-key>'

Response (200 OK)

{
  "id": "usr_01hvbp4nrtemk6wjq8xcgdfy2s",
  "email": "you@example.com",
  "role": "admin",
  "organization_id": "org_01hv3qxmpkyndzcwbt8fj6r90e",
  "kb_clearance_level": 30
}

kb_clearance_level controls which knowledge-base documents your assistants can retrieve. A higher number means access to more sensitive content tiers. See the Knowledge Bases concept for details.

Create an assistant

An assistant is the AI actor behind your conversations. Create one by posting a name and system prompt. Feather provisions the assistant, an initial revision, and a bound workflow — and returns all three.

Create Assistant

curl -X POST https://api-sandbox.featherhq.com/v1/assistants \
  -H 'x-api-key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Support Bot",
    "description": "Answers customer questions about our product.",
    "system_prompt": "You are a friendly support assistant. Answer concisely."
  }'

Response (201 Created)

{
  "agent": {
    "id": "agt_01hx2rp7tqkwn5cbms0evuy4dj",
    "name": "Support Bot",
    "active_revision_id": null
  },
  "agent_revision": {
    "id": "rev_01hx2rp7vznlm8fbqt9gscwo3k",
    "agent_id": "agt_01hx2rp7tqkwn5cbms0evuy4dj"
  },
  "workflow_revision_id": "wfr_01hx2rp7wy3nk9dbrs0abcd12"
}

New assistants start inactive (active_revision_id is null). Save agent.id and agent_revision.id for the next step.

Activate the revision

Make the assistant live by activating its initial revision. This points the assistant’s active_revision_id at that revision so it can serve conversations.

Activate Revision

curl -X POST https://api-sandbox.featherhq.com/v1/assistants/agt_01hx2rp7tqkwn5cbms0evuy4dj/revisions/rev_01hx2rp7vznlm8fbqt9gscwo3k/activate \
  -H 'x-api-key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{"activation_reason": "quickstart"}'

The assistant is now active. There is no separate “publish” step — activating a revision is what makes it live.

Start a conversation

Open a conversation with POST /v1/conversations. Reference your assistant with assistant_id, and identify the end user with your own stable identifier via org_external_end_user_id — Feather creates the end user for you if it doesn’t exist yet.

Start Conversation

curl -X POST https://api-sandbox.featherhq.com/v1/conversations \
  -H 'x-api-key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "assistant_id": "agt_01hx2rp7tqkwn5cbms0evuy4dj",
    "org_external_end_user_id": "quickstart-user-1"
  }'

Response (201 Created)

{
  "id": "ses_01hxkqm3pj7ftv9rbew5cydnug",
  "end_user_id": "usr_01hvbp4nrtemk6wjq8xcgdfy2s",
  "channel": "chat",
  "surface": "direct_api",
  "assistant_id": "agt_01hx2rp7tqkwn5cbms0evuy4dj",
  "assistant_revision_id": "rev_01hx2rp7vznlm8fbqt9gscwo3k",
  "session_type": "live",
  "status": "active",
  "created_at": "2026-01-15T10:36:00Z"
}

Copy the conversation id — you’ll need it to send messages. API-key callers always create chat, live conversations; passing session_type: test or simulation from an API key returns 422 (those run only from the dashboard).

Send a message

Send the first user message by posting a turn. Feather runs it through your assistant and returns the reply along with the session status.

Send a Message

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

Response (201 Created)

{
  "turn_id": "trn_01hxkqn8sv2gep0qmzr7byft4c",
  "conversation_id": "ses_01hxkqm3pj7ftv9rbew5cydnug",
  "text": "Hi there! Absolutely — I'm Support Bot, and I'm here to help. What can I do for you today?",
  "session_status": "active",
  "message_seqs": [0, 1],
  "ended": false
}

You’ve run your first end-to-end Feather conversation. Branch on session_status: while it’s active, keep sending turns. If it becomes awaiting_approval or waiting_for_human, poll GET /v1/conversations/{id}/messages until it returns to active or closes.

Next steps

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

Build a fuller assistant

Attach a knowledge base and custom tools so your assistant answers grounded in your own data.

Ingest your docs

Upload files, crawl URLs, or sync from Notion and Google Drive to populate a knowledge base.

Stream responses

Use the streaming turns endpoint to deliver low-latency, token-by-token replies.

Evaluate quality

Run simulation suites and model-judge evaluators to measure and improve performance.

Get Started

Core Concepts

Guides

Channels

Get Started with Feather in Under 5 Minutes

Next steps

Build a fuller assistant

Ingest your docs

Stream responses

Evaluate quality

​Next steps

Build a fuller assistant

Ingest your docs

Stream responses

Evaluate quality

Next steps