Skip to main content
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.
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.
1

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.
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,
  "last_used_at": null,
  "expires_at": null,
  "created_at": "2025-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.
2

Verify your identity

Confirm your key works and check which organization and role it belongs to by calling GET /v1/identity/whoami.
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": 3,
  "created_at": "2025-01-01T09:00:00Z"
}
Note your organization_id — you will need it when configuring agents and conversations in later steps.
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 concept page for details.
3

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.
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."
  }'
Response (201 Created)
{
  "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.
4

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.
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"
  }'
Response (201 Created)
{
  "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.
5

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.
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?"
  }'
Response (200 OK)
{
  "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.

​
Next Steps

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

Add a Knowledge Base

Connect a knowledge base to your agent so it can answer questions grounded in your own documents and data.

Ingest Your Docs

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

Stream Responses

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

Evaluate Quality

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