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

# Quickstart

> From an API key to a live answer in under ten minutes

This walks from a fresh key to a generative answer. Everything is one `curl` away.

<Steps>
  <Step title="Create a key">
    In the console, **Configuration → API keys → Create key**. Give it the scopes `landings:write`, `knowledge:write`, `knowledge:read` and `chat:write`, and copy the secret; it is shown once. Write never implies read: `knowledge:read` is what polling sources and the retrieval probe below need.

    ```bash theme={null}
    export WDY_KEY="wdy_live_…"
    export WDY="https://api.wondeya.com/v1"
    ```
  </Step>

  <Step title="Confirm the key works">
    ```bash theme={null}
    curl $WDY/me -H "Authorization: Bearer $WDY_KEY"
    # → { "workspaceId": "…", "scopes": ["landings:write","knowledge:write","knowledge:read","chat:write"] }
    ```
  </Step>

  <Step title="Create an agent">
    An agent is the brain the conversation answers from.

    ```bash theme={null}
    curl -X POST $WDY/agents \
      -H "Authorization: Bearer $WDY_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "name": "Support", "identity": { "businessName": "Acme", "description": "We sell widgets." } }'
    # → { "id": "AGENT_ID", "name": "Support", … }
    ```
  </Step>

  <Step title="Teach it something">
    Add a fact. Ingestion is asynchronous: this answers `202` with the source `pending`.

    ```bash theme={null}
    curl -X POST $WDY/knowledge/text \
      -H "Authorization: Bearer $WDY_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "title": "Pricing", "text": "## Pricing\nThe Pro plan is 39 USD per month.", "topics": ["pricing"], "agentId": "AGENT_ID" }'
    ```

    Poll `GET $WDY/knowledge/sources` until the source is `ready`.
  </Step>

  <Step title="Ask it something">
    The generative turn spends one message credit and returns the answer plus any components it chose to render.

    ```bash theme={null}
    curl -X POST $WDY/agents/AGENT_ID/chat \
      -H "Authorization: Bearer $WDY_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "message": "How much is the Pro plan?" }'
    # → { "conversationId": "…", "reply": "The Pro plan is 39 USD per month.", "components": [ … ], "cached": false }
    ```

    Continue the conversation by passing the `conversationId` back. For a token-by-token stream, send `Accept: text/event-stream`.
  </Step>
</Steps>

## Before you ask, probe

To see what an agent would retrieve WITHOUT spending a credit, use the retrieval probe:

```bash theme={null}
curl -X POST $WDY/agents/AGENT_ID/query \
  -H "Authorization: Bearer $WDY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "how much does it cost", "topics": ["pricing"] }'
# → { "passages": [ … ], "strategies": { "topics": 1, "vector": 0 } }
```

Empty passages mean the agent cannot answer that question yet. Add knowledge and try again.