Quickstart
From nothing to a first answer in about five minutes. You need a browser, curl, and an account at Google or
GitHub whose email address is verified there.
1. Get access to a workspace
Section titled “1. Get access to a workspace”A workspace holds your data sources, questions and dashboards. You cannot create one yourself yet: ask the Loupestack team to create one for you, or to add your email address to an existing one. You become a member the next time you log in with that address.
TODO: describe self-service sign-up once it exists.
2. Log in and copy your session cookie
Section titled “2. Log in and copy your session cookie”The API uses a session cookie, not an API key (Authentication).
-
Open
https://api.dev.loupestack.com/healthzin your browser. It answers{"status":"ok"}. -
Open the browser’s developer console on that page and run this, with
googleorgithub:fetch('/api/auth/sign-in/social', {method: 'POST',headers: { 'content-type': 'application/json' },body: JSON.stringify({ provider: 'google', callbackURL: '/healthz' }),}).then((r) => r.json()).then((r) => { location.href = r.url; }); -
Approve the login at Google or GitHub. You land back on
/healthz, now logged in. -
In the developer tools, open the cookies of
api.dev.loupestack.comand copy the value of__Secure-better-auth.session_token.
Keep it in a shell variable for the next steps. It is valid for 8 hours, and treat it like a password:
export LOUPESTACK_SESSION='paste-the-cookie-value-here'3. Who am I?
Section titled “3. Who am I?”curl https://api.dev.loupestack.com/v1/me \ --cookie "__Secure-better-auth.session_token=$LOUPESTACK_SESSION"{ "user": { "id": "usr_3fT8kZ2bQ6vR9yWc", "name": "Owner A", "email": "owner@example.com" }, "organization": { "id": "org_7Hq2LwX9pD4mN1sK", "name": "Example Retail", "slug": "example-retail", "role": "owner" }, "organizations": [{ "id": "org_7Hq2LwX9pD4mN1sK", "name": "Example Retail", "slug": "example-retail", "role": "owner" }]}organization is your active workspace. If it is null, you are not a member of a workspace yet (step 1).
4. What data can I query?
Section titled “4. What data can I query?”curl https://api.dev.loupestack.com/v1/sources \ --cookie "__Secure-better-auth.session_token=$LOUPESTACK_SESSION"The answer lists the tables of your workspace’s lake and of each live source, with their columns. An empty list
means nothing is connected yet: an owner or admin adds a source with
POST /v1/connectors.
5. Ask a question
Section titled “5. Ask a question”Requests that change something, like this one, must also send an Origin header
(why). The answer streams back as
server-sent events; -N makes curl print them as they arrive.
curl -N https://api.dev.loupestack.com/v1/ask \ --cookie "__Secure-better-auth.session_token=$LOUPESTACK_SESSION" \ --header 'Origin: https://api.dev.loupestack.com' \ --header 'Content-Type: application/json' \ --data '{ "question": "How many customers do we have?" }'event: generatingdata: {"conversationId":"3d4e5f60-7182-4930-9c4d-5e6f7a8b9cad"}
event: runningdata: {"attempt":1}
event: answerdata: {"conversationId":"3d4e5f60-7182-4930-9c4d-5e6f7a8b9cad","messageId":"5f607182-93a4-4b52-9e6f-7a8b9cadbecf","summary":"You have 50 customers.","explanation":"Counted the rows of lake.customers.","executedSql":"SELECT count(*) AS customers FROM lake.customers","columns":[{"name":"customers","type":"BIGINT"}],"rows":[[50]],"truncated":false}POST /v1/chattakes any message, including “create a dashboard around new customers”, and picks the flow for you.- Conventions covers paging, limits and retries; Errors every error code.