Quickstart

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

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.

export WDY_KEY="wdy_live_…"
export WDY="https://api.wondeya.com/v1"

Confirm the key works

curl $WDY/me -H "Authorization: Bearer $WDY_KEY"
# → { "workspaceId": "…", "scopes": ["landings:write","knowledge:write","knowledge:read","chat:write"] }

Create an agent

An agent is the brain the conversation answers from.

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", … }

Teach it something

Add a fact. Ingestion is asynchronous: this answers 202 with the source pending.

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.

Ask it something

The generative turn spends one message credit and returns the answer plus any components it chose to render.

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.

Before you ask, probe

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

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.

Overview

Endpoints

Before you ask, probe

​Before you ask, probe

Before you ask, probe